chainlit

Chainlit

使用 Python 构建可用于生产环境、具有丰富界面的对话式 AI 应用。

安装

pip install chainlit

快速入门

import chainlit as cl

@cl.on_message
async def on_message(message: cl.Message):
    await cl.Message(content=f"You said: {message.content}").send()

运行命令：

chainlit run app.py -w

核心概念

概念	描述
消息	用户与助手之间的文本交流
步骤	可见的处理阶段（大模型调用、工具使用）
元素	丰富的界面内容（图像、文件、图表、数据帧）
操作	带有回调的交互式按钮
会话	按用户管理状态

生命周期钩子

import chainlit as cl

@cl.on_chat_start
async def start():
    cl.user_session.set("history", [])
    await cl.Message(content="Hello!").send()

@cl.on_message
async def on_message(message: cl.Message):
    await cl.Message(content="Got it!").send()

@cl.on_chat_end
async def end():
    print("Session ended")

流式响应

from openai import AsyncOpenAI
import chainlit as cl

client = AsyncOpenAI()
cl.instrument_openai()

@cl.on_message
async def on_message(message: cl.Message):
    msg = cl.Message(content="")
    await msg.send()

    stream = await client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": message.content}],
        stream=True
    )

    async for chunk in stream:
        if token := chunk.choices[0].delta.content:
            await msg.stream_token(token)

    await msg.update()

步骤（思维链）

@cl.step(type="tool")
async def search(query: str):
    return f"Results for: {query}"

@cl.step(type="llm")
async def generate(context: str):
    return await llm_call(context)

@cl.on_message
async def on_message(message: cl.Message):
    results = await search(message.content)
    answer = await generate(results)
    await cl.Message(content=answer).send()

用户会话

@cl.on_chat_start
async def start():
    cl.user_session.set("counter", 0)

@cl.on_message
async def on_message(message: cl.Message):
    count = cl.user_session.get("counter")
    count += 1
    cl.user_session.set("counter", count)

请求用户输入

# Text input
response = await cl.AskUserMessage(content="What's your name?").send()
name = response.get("output") if response else "Anonymous"

# File upload
files = await cl.AskFileMessage(
    content="Upload a file",
    accept=["text/plain", "application/pdf"]
).send()

# Action selection
response = await cl.AskActionMessage(
    content="Choose:",
    actions=[
        cl.Action(name="yes", label="Yes"),
        cl.Action(name="no", label="No"),
    ]
).send()

界面元素

@cl.on_message
async def on_message(message: cl.Message):
    elements = [
        cl.Text(name="code.py", content="print('hello')", language="python"),
        cl.Image(name="chart", path="./chart.png", display="inline"),
        cl.File(name="report.pdf", path="./report.pdf"),
    ]

    await cl.Message(content="Results:", elements=elements).send()

操作（按钮）

@cl.action_callback("approve")
async def on_approve(action: cl.Action):
    await action.remove()
    await cl.Message(content="Approved!").send()

@cl.on_message
async def on_message(message: cl.Message):
    actions = [cl.Action(name="approve", label="Approve")]
    await cl.Message(content="Review:", actions=actions).send()

参考文档

详细指南：

• lifecycle.md - on_chat_start、on_message、on_chat_end 钩子
• messages.md - Message 类、流式传输、chat_context
• steps.md - Step 装饰器、上下文管理器、嵌套步骤
• elements.md - Text、Image、File、PDF、Audio、Video、Plotly
• actions.md - 操作按钮、回调、有效负载
• ask-user.md - AskUserMessage、AskFileMessage、AskActionMessage
• session.md - 用户会话、保留键、状态管理
• auth.md - 密码、OAuth、标头身份验证
• integrations.md - OpenAI、LangChain、LlamaIndex、Mistral
• patterns.md - RAG、文档问答、多 Agent、反馈

集成

# OpenAI
cl.instrument_openai()

# LangChain
config = RunnableConfig(callbacks=[cl.LangchainCallbackHandler()])

# LlamaIndex
callback_manager = CallbackManager([cl.LlamaIndexCallbackHandler()])

配置

.chainlit/config.toml：

[project]
name = "My App"

[UI]
cot = "full"  # Show chain of thought: full, hidden, tool_call

运行命令

# Development with auto-reload
chainlit run app.py -w

# Production
chainlit run app.py --host 0.0.0.0 --port 8000

# Generate auth secret
chainlit create-secret

关键导入

import chainlit as cl

# Core
cl.Message, cl.Step, cl.Action

# Elements
cl.Text, cl.Image, cl.File, cl.Pdf, cl.Audio, cl.Video
cl.Plotly, cl.Dataframe, cl.TaskList

# Ask User
cl.AskUserMessage, cl.AskFileMessage, cl.AskActionMessage

# Decorators
@cl.on_chat_start, @cl.on_message, @cl.on_chat_end
@cl.step, @cl.action_callback
@cl.password_auth_callback, @cl.oauth_callback