nanobot步骤详解：Chainlit前端自定义UI、消息流样式与响应格式控制

优质文章学习记录

11 Apr 2026 — 13 min read

nanobot步骤详解：Chainlit前端自定义UI、消息流样式与响应格式控制

1. 引言：为什么你需要关注nanobot？

如果你正在寻找一个轻量级、易部署、功能却足够强大的AI助手框架，那么nanobot的出现可能会让你眼前一亮。它就像一个精简版的“瑞士军刀”，在保持核心功能完整的同时，将代码量压缩到了惊人的程度。

想象一下，你只需要大约4000行代码，就能获得一个具备智能对话、工具调用能力的AI代理。这比动辄数十万行的同类项目要清爽得多。nanobot内置了vLLM部署的Qwen3-4B-Instruct-2507模型，开箱即用，还提供了基于Chainlit的现代化Web界面，让你能像聊天一样与AI交互。

更棒的是，它支持通过简单的配置，将智能助手的能力扩展到QQ等即时通讯平台。这意味着你可以打造一个专属的、24小时在线的智能客服或私人助理。

本文将带你一步步深入nanobot，重点讲解如何通过Chainlit这个强大的前端框架，来自定义交互界面、控制消息的显示样式，以及精确管理AI的响应格式。无论你是想快速搭建一个演示原型，还是希望深度定制用户体验，这里都有你需要的答案。

2. nanobot初探：核心架构与快速启动

在深入定制之前，我们先快速了解一下nanobot是什么，以及如何让它跑起来。

2.1 nanobot是什么？

简单来说，nanobot是一个超轻量级的AI代理框架。它的设计哲学是“小而美”，在保证核心代理功能（如规划、工具调用、记忆）可用的前提下，极力追求代码的简洁和部署的便捷。

轻量级：核心代码仅约4000行，相比庞大的同类项目，学习和维护成本极低。
内置模型：预置了通过vLLM高效服务的Qwen3-4B-Instruct-2507模型，无需额外部署。
多前端支持：默认提供基于Chainlit的Web UI，同时支持通过网关（Gateway）接入其他平台，如QQ机器人。
易于扩展：清晰的模块化设计，方便你添加新的工具或集成新的通信渠道。

2.2 一键部署与验证

假设你已经通过镜像等方式获得了nanobot的运行环境，启动过程通常非常直接。

首先，我们需要确认核心的模型服务是否已成功启动。打开终端或WebShell，检查日志文件：

cat /root/workspace/llm.log

如果看到类似模型加载成功、服务监听端口的日志信息，就说明vLLM已经将Qwen模型部署好了，nanobot的后端引擎已经就绪。

接下来，启动Chainlit前端界面。通常，运行一个简单的命令即可：

chainlit run app.py

或者根据项目具体的入口文件来启动。成功启动后，在浏览器中访问提示的地址（通常是 http://localhost:8000），你就能看到一个简洁的聊天界面了。

3. 深入Chainlit：打造个性化的聊天前端

Chainlit是一个专门为构建AI应用聊天界面而生的Python库。它让创建交互式应用变得像写脚本一样简单。nanobot利用Chainlit作为其默认的Web界面，而我们则可以对这个界面进行深度定制。

3.1 理解Chainlit的核心概念

要自定义UI，得先明白Chainlit是如何工作的。它的核心是围绕“消息”和“步骤”来构建的。

消息（Message）：这是用户和AI之间交换的主要内容。可以是文本、图片、文件等。Chainlit允许你精细控制每条消息的样式、发送者和显示方式。
步骤（Step）：代表一个异步的、可能长时间运行的任务。例如，AI思考的过程、调用一个外部工具。步骤可以展开显示详细信息，也可以折叠起来，非常适合展示AI的“思考链”。
回调函数（Callbacks）：使用 @cl.on_message， @cl.on_chat_start 等装饰器，你可以定义当特定事件发生时（如收到用户消息、聊天开始）程序应该执行什么逻辑。

nanobot已经搭建好了基本的回调函数框架，将用户输入路由到AI模型进行处理。我们的定制工作，主要是在这个框架内“化妆”和“调整流程”。

3.2 自定义消息样式与头像

默认的聊天界面可能比较朴素。Chainlit允许我们轻松地改变这一点。

1. 修改用户和AI的头像与名称： 你可以在Chainlit应用的入口文件（如 app.py）中，通过 cl.setting 进行全局配置。

import chainlit as cl @cl.setting def settings(): return [ cl.Setting( name="AI Assistant Name", value="我的智能助手", # 给AI起个名字 description="The name of the AI Assistant" ), cl.Setting( name="User Name", value="开发者", # 自定义用户显示名 description="The name of the User" ) ]

更常见的做法是在发送消息时直接指定。nanobot的消息发送逻辑可能封装在某个函数中，你需要找到它并添加参数：

# 假设在某个处理函数中，准备发送AI的回复 async def send_ai_response(content): # 创建一个消息对象，并指定发送者信息 msg = cl.Message( content=content, author="AI助手", avatar="https://example.com/ai_avatar.png" # 可以指向一个在线头像图片 ) await msg.send()

2. 丰富消息内容格式： Chainlit的 Message 对象支持发送不仅仅是纯文本。

# 发送带Markdown格式的消息 msg = cl.Message(content="**这是加粗文本**，`这是代码`，[这是一个链接](https://example.com)") await msg.send() # 发送图片（假设本地路径或URL） elements = [ cl.Image(name="示例图片", path="./example.png", display="inline") ] await cl.Message(content="请看下面的图表：", elements=elements).send()

通过组合这些元素，你可以让AI的回复更加直观和美观。

3.3 控制消息流与响应节奏

直接一次性返回大段文本体验并不好。Chainlit支持“流式”响应，让文字像真人打字一样一个个出现，这能极大提升交互感。

nanobot可能已经使用了流式输出。如果没有，或者你想进一步控制，可以这样做：

import asyncio async def stream_response_manually(text): # 创建一个空消息 msg = cl.Message(content="") await msg.send() # 模拟流式输出 for chunk in text.split(" "): # 这里按单词拆分，你可以按字符或句子 await msg.stream_token(chunk + " ") await asyncio.sleep(0.05) # 控制输出速度 # 流式完成后，更新最终消息 await msg.update()

更重要的是，你可以利用Chainlit的“步骤”功能来可视化AI的思考过程。这对于展示nanobot调用工具、进行推理的中间状态非常有用。

async def process_user_query(query): # 显示一个“思考中”的步骤 with cl.Step(name="分析用户问题", type="run") as step: step.output = "正在理解您的指令..." # ... 这里是分析逻辑 step.output = "分析完成，准备调用工具。" # 显示一个“执行工具”的步骤 with cl.Step(name="执行系统命令", type="tool") as step: step.output = "正在执行: `nvidia-smi`" # ... 这里是调用工具的逻辑 result = "NVIDIA-SMI 470.161.03 ..." # 模拟结果 step.output = f"命令执行成功！\n```\n{result}\n```" # 最终回复 await cl.Message(content="已为您查询显卡信息，详见上方步骤。").send()

这样，用户就能清晰地看到AI是如何一步步解决问题的，而不是一个“黑箱”。

4. 高级控制：响应格式与结构化输出

有时，我们不仅希望AI回复内容，还希望它以特定的、结构化的格式回复，以便后续程序自动处理。这需要对nanobot与模型交互的部分进行干预。

4.1 引导模型生成结构化回复

大型语言模型可以通过“系统提示词”来引导其输出格式。你可以在nanobot配置或与vLLM模型交互的代码中，修改或追加系统指令。

例如，如果你希望AI在回答关于系统状态的问题时，始终以JSON格式返回，可以在提示词中加入：

你是一个智能系统助手。当用户询问系统信息（如显卡、内存、进程）时，请严格按照以下JSON格式回复，不要包含任何其他解释性文字： { "command": "用户询问的实际命令", "summary": "信息的简要中文总结", "details": "命令返回的原始详细信息" }

然后，在Chainlit前端，你可以解析这个JSON，并以更友好的方式展示：

import json async def handle_structured_response(model_raw_output): try: data = json.loads(model_raw_output) # 创建更友好的展示 content = f"**{data['summary']}**\n\n" content += f"执行命令：`{data['command']}`\n\n" content += f"```\n{data['details']}\n```" await cl.Message(content=content).send() except json.JSONDecodeError: # 如果不是JSON，按普通消息处理 await cl.Message(content=model_raw_output).send()

4.2 利用Chainlit Elements进行复杂渲染

对于更复杂的结构化数据，Chainlit的 Elements 功能非常强大。你可以用它来渲染表格、文件树、PDF等。

假设AI分析了一段数据并生成了一个列表：

# 假设AI返回的数据结构 analysis_result = { "items": [ {"name": "进程A", "cpu": "15%", "memory": "200MB"}, {"name": "进程B", "cpu": "45%", "memory": "1.2GB"}, ] } # 使用Chainlit的DataFrame元素（需要pandas） import pandas as pd df = pd.DataFrame(analysis_result["items"]) elements = [cl.DataFrame(df)] # 这将渲染成一个交互式表格 await cl.Message(content="系统进程分析结果：", elements=elements).send()

通过这种方式，你可以将AI生成的原始文本，转化为用户更容易理解和操作的界面元素。

5. 实战：集成QQ机器人并统一前端体验

nanobot的一个亮点是可以通过网关（Gateway）轻松接入其他平台。我们以接入QQ机器人为例，并探讨如何保持与Chainlit前端一致的交互体验。

5.1 配置QQ机器人通道

根据提供的指南，接入QQ机器人主要分为几步：

注册与创建：访问QQ开放平台，注册开发者并创建一个机器人应用，获取 AppID 和 AppSecret。
启动网关服务：运行 nanobot gateway 命令。这个服务会作为桥梁，接收来自QQ平台的消息，转发给nanobot核心处理，再将回复传回QQ。

修改nanobot配置：编辑nanobot的配置文件（例如 /root/.nanobot/config.json），在 channels 部分启用并配置QQ通道。

{ "channels": { "qq": { "enabled": true, "appId": "YOUR_APP_ID_HERE", "secret": "YOUR_APP_SECRET_HERE", "allowFrom": [] // 可以留空或指定允许的QQ号/群 } } }

5.2 跨平台的消息样式适配

现在你有了两个前端：华丽的Chainlit网页和QQ聊天窗口。如何让AI的回复在不同平台上都有好体验？

关键在于 消息处理层的抽象。nanobot的核心逻辑（调用模型、工具）应该与前端展示分离。我们可以创建一个“消息格式化器”。

# 一个简单的消息格式化器示例 class MessageFormatter: @staticmethod def for_web(content, data=None): """为Chainlit Web界面格式化消息""" if data and data.get("type") == "system_info": # 如果是系统信息，用代码块和步骤展示 return self._create_web_system_message(data) else: # 普通文本，支持Markdown return cl.Message(content=content) @staticmethod def for_qq(content, data=None): """为QQ平台格式化消息""" if data and data.get("type") == "system_info": # QQ中可能不适合复杂格式，简化处理 summary = data.get("summary", "") details = data.get("details", "")[:500] # 截断长文本 return f"{summary}\n\n详情：\n{details}" else: # QQ中可能不支持Markdown，返回纯文本 return content.replace('**', '').replace('`', '') def _create_web_system_message(self, data): # 创建包含步骤和代码块的复杂消息（参考3.3节） # ... 具体实现 pass # 在nanobot的核心处理函数中 async def process_and_respond(user_input, channel="web"): # 1. 核心逻辑处理，得到原始结果和元数据 raw_result, metadata = await core_agent_process(user_input) # 2. 根据渠道选择格式化器 formatter = MessageFormatter() if channel == "web": response = formatter.for_web(raw_result, metadata) await response.send() # Chainlit发送 elif channel == "qq": response_text = formatter.for_qq(raw_result, metadata) await qq_gateway.send(response_text) # 通过网关发送给QQ

这样，无论用户从哪个渠道提问，都能获得渠道最优化的回复体验，而你只需要维护一套核心逻辑和格式化规则。

6. 总结

通过本文的探讨，你应该对nanobot这个轻量级AI助手框架，以及如何通过Chainlit定制其前端界面有了深入的了解。我们来回顾一下关键点：

快速启动：nanobot凭借其极简设计和内置模型，让你能快速获得一个可用的智能对话代理。
UI定制核心：Chainlit的 消息（Message）、步骤（Step） 和 元素（Elements） 是构建丰富交互的三大基石。通过它们，你可以控制头像、名称、实现流式输出，并可视化AI的思考过程。
响应格式控制：通过 系统提示词工程 和 后端解析逻辑，你可以引导模型输出结构化数据（如JSON），并在前端进行优雅的渲染，提升可读性和可用性。
多平台体验统一：在接入像QQ机器人这样的多通道时，设计一个 消息格式化抽象层 至关重要。它能确保核心逻辑复用，同时为不同平台提供最合适的展示样式。

nanobot的简洁架构给了开发者巨大的定制空间。从修改Chainlit的UI样式，到控制复杂的交互流，再到统一跨平台输出，每一步你都可以根据实际需求进行裁剪和增强。动手试试吧，用这些技巧打造一个独一无二的、体验出色的AI助手。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 ZEEKLOG星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

nanobot步骤详解：Chainlit前端自定义UI、消息流样式与响应格式控制

优质文章学习记录