Ultrabot：30 课程开发指南 - 第1课

Ultrabot30 课程开发指南从零开始构建一个生产级 AI 助手框架。本指南将带你从向 LLM 问好一步步走到一个完整的多提供者、多通道 AI 智能体具备工具调用、记忆、安全防护和 Web 界面。每节课程都建立在上一节课的基础之上。每节课都包含可运行的代码和测试。本教程的主要思路来自于Nanobot(https://github.com/HKUDS/nanobot)以及Learn-Claude-Code(https://github.com/shareAI-lab/learn-claude-code/)所以对应的叫做Ultrabot。本课程设计由AI辅助下完成更新地址见https://github.com/junfhu/UltrabotStepByStep如果您觉得对您有帮助请帮助点亮一颗星。本课程中使用的大模型提供商是火山引擎Code Plan如果正好你也需要可以使用我的邀请码获取9折优惠 https://volcengine.com/L/_01BJCkKdMc/ 邀请码HHCDB4J4课程 1向 LLM 问好 – 你的第一次 AI 对话目标用 10 行 Python 和 LLM 对话然后逐步构建一个支持任意 OpenAI 兼容提供者的多轮聊天机器人。你将学到OpenAI chat completions API 的工作原理消息列表模式system / user / assistant 角色如何将客户端指向任意OpenAI 兼容提供者我们这里用火山引擎如何构建多轮对话循环新建文件chat.py– 一个可以立即运行的单文件聊天机器人步骤 0使用 pyenv 安装 Python 3.12本指南全程使用pyenv管理 Python 版本。如果你还没有安装请参阅介绍页。# 安装 Python 3.12如果已安装可跳过pyenvinstall3.12pyenv global3.12# 创建项目目录和虚拟环境mkdir-pultrabotcdultrabot python-mvenv .venvsource.venv/bin/activate# 验证python--version# Python 3.12.x每次开始工作前都要激活虚拟环境source .venv/bin/activate步骤 1安装唯一的依赖pipinstallopenai就这样。一个包。不需要项目脚手架不需要配置文件。openaiPython SDK可以与任何暴露 OpenAI 兼容 API 的提供者一起使用 – 不仅仅是 OpenAI 本身。步骤 2设置LLM相关的环境变量export OPENAI_BASE_URLhttps://ark.cn-beijing.volces.com/api/coding/v3 export MODELminimax-m2.5 export OPENAI_API_KEYsk-...步骤 3向 LLM 打个招呼创建chat.py# chat.py -- 你的第一次 AI 对话importosfromopenaiimportOpenAI# 三个环境变量控制你与哪个 LLM 对话# OPENAI_API_KEY -- 你的 API 密钥# OPENAI_BASE_URL -- 提供者的基础 URL# MODEL -- 模型名称clientOpenAI(api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),)modelos.getenv(MODEL)responseclient.chat.completions.create(modelmodel,messages[{role:user,content:Hello!}],)print(response.choices[0].message.content)运行python chat.py你应该能看到模型返回的友好问候。这就是整个 OpenAI 兼容 chat API你发送一个消息列表得到一个回复。无论你调用的是 OpenAI、DeepSeek 还是本地模型同一份代码都能工作。步骤 4理解消息格式每个 OpenAI chat 请求接收一个messages列表。每条消息是一个包含role和content的字典角色用途system设定 AI 的性格和规则user人类说的话assistantAI 说的话用于对话历史记录这是每个 LLM 聊天机器人的基础数据结构。UltraBot 的整个智能体循环我们将在课程 2 中构建就是围绕管理这个列表展开的。步骤 5添加系统提示词# chat.py -- 现在有了个性importosfromopenaiimportOpenAI clientOpenAI(api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),)modelos.getenv(MODEL)# 系统提示词设定 AI 的行为 -- 就像 ultrabot 的# ultrabot/agent/prompts.py 中的 DEFAULT_SYSTEM_PROMPTSYSTEM_PROMPTYou are UltraBot, a helpful personal AI assistant. - Answer concisely and accurately. - When unsure, say so rather than guessing. - Use code blocks for any code in your responses.responseclient.chat.completions.create(modelmodel,messages[{role:system,content:SYSTEM_PROMPT},{role:user,content:What is Pythons GIL?},],)print(response.choices[0].message.content)步骤 6构建多轮对话关键洞察要进行对话你需要维护一个不断增长的messages列表。每次助手回复后将其追加到列表然后追加下一条用户消息。# chat.py -- 完整的多轮聊天机器人适用于任何 OpenAI 兼容提供者importosfromopenaiimportOpenAI clientOpenAI(api_keyos.getenv(OPENAI_API_KEY),base_urlos.getenv(OPENAI_BASE_URL),)modelos.getenv(MODEL)SYSTEM_PROMPTYou are UltraBot, a helpful personal AI assistant. - Answer concisely and accurately. - When unsure, say so rather than guessing. - Use code blocks for any code in your responses.# 对话历史 -- 这是核心数据结构messages:list[dict][{role:system,content:SYSTEM_PROMPT}]print(fUltraBot ready (model{model}). Type exit to quit.\n)whileTrue:user_inputinput(you ).strip()ifnotuser_input:continueifuser_input.lower()in(exit,quit):print(Goodbye!)break# 1. 将用户消息追加到历史记录messages.append({role:user,content:user_input})# 2. 将完整历史记录发送给 LLMresponseclient.chat.completions.create(modelmodel,messagesmessages,)# 3. 提取助手的回复assistant_messageresponse.choices[0].message.content# 4. 将助手的回复追加到历史记录这就是让对话变成# 多轮的关键 -- LLM 能看到之前所有内容messages.append({role:assistant,content:assistant_message})print(f\nassistant {assistant_message}\n)这种模式 – 追加用户消息、调用 LLM、追加助手回复、循环 – 是每一个AI 聊天机器人的核心。UltraBot 的Agent.run()方法在ultrabot/agent/agent.py中做的就是同样的事情只是在上面叠加了更多功能。步骤 7添加一个最简的 pyproject.toml后面的课程中需要它来让pip install -e .生效。现在先保持最简# pyproject.toml [project] name ultrabot version 0.1.0 requires-python 3.11 dependencies [openai1.0] [build-system] requires [hatchling] build-backend hatchling.build测试创建tests/test_session1.py# tests/test_session1.py课程 1 的测试 -- 消息格式、环境变量配置和响应解析。importosimportpytestdeftest_message_format():验证我们的消息列表具有正确的结构。messages[{role:system,content:You are a helper.},{role:user,content:Hello!},]# 每条消息必须包含 role 和 contentformsginmessages:assertroleinmsgassertcontentinmsgassertmsg[role]in(system,user,assistant,tool)deftest_multi_turn_history():验证对话历史记录正确增长。messages[{role:system,content:You are a helper.}]# 模拟一个两轮对话messages.append({role:user,content:Hi})messages.append({role:assistant,content:Hello!})messages.append({role:user,content:How are you?})messages.append({role:assistant,content:Im great!})assertlen(messages)5assertmessages[0][role]systemassertmessages[1][role]userassertmessages[2][role]assistant# 在系统提示词之后角色交替出现 user/assistantforiinrange(1,len(messages)):expecteduserifi%21elseassistantassertmessages[i][role]expecteddeftest_default_model():未设置 MODEL 环境变量时默认为 gpt-4o-mini。origos.environ.pop(MODEL,None)try:modelos.getenv(MODEL,gpt-4o-mini)assertmodelgpt-4o-minifinally:iforigisnotNone:os.environ[MODEL]origdeftest_custom_model(monkeypatch):MODEL 环境变量可覆盖默认模型。monkeypatch.setenv(MODEL,deepseek-chat)modelos.getenv(MODEL,gpt-4o-mini)assertmodeldeepseek-chatdeftest_custom_base_url(monkeypatch):OPENAI_BASE_URL 环境变量用于配置提供者端点。monkeypatch.setenv(OPENAI_BASE_URL,https://api.deepseek.com)base_urlos.getenv(OPENAI_BASE_URL)assertbase_urlhttps://api.deepseek.comdeftest_base_url_none_when_unset():OPENAI_BASE_URL 未设置时默认为 None使用 OpenAI 端点。origos.environ.pop(OPENAI_BASE_URL,None)try:base_urlos.getenv(OPENAI_BASE_URL)assertbase_urlisNonefinally:iforigisnotNone:os.environ[OPENAI_BASE_URL]origdeftest_response_parsing_mock(monkeypatch):测试我们能否正确解析 OpenAI 响应使用 mock。fromunittest.mockimportMagicMock# 构建一个模拟的响应看起来像 OpenAI 返回的结果mock_messageMagicMock()mock_message.contentHello! How can I help?mock_choiceMagicMock()mock_choice.messagemock_message mock_responseMagicMock()mock_response.choices[mock_choice]# 这就是我们在 chat.py 中解析它的方式resultmock_response.choices[0].message.contentassertresultHello! How can I help?运行测试pipinstallpytest pytest tests/test_session1.py-v检查点# 使用任意提供者 -- 设置环境变量后运行python chat.py预期输出UltraBot ready (modelminimax-m2.5). Type exit to quit. you What is 2 2? assistant 2 2 equals 4. you And multiply that by 10? assistant 4 multiplied by 10 equals 40. you exit Goodbye!模型记住了之前的对话轮次因为我们每次都发送了完整的messages列表。由于我们从环境变量读取OPENAI_BASE_URL和MODEL同一份代码可以用于任何兼容OPENAI的大模型提供商。本课成果一个完整的单文件多轮聊天机器人支持任意OpenAI 兼容提供者。三个环境变量OPENAI_API_KEY、OPENAI_BASE_URL、MODEL让你无需修改代码即可切换提供者。消息列表模式system 交替的user/assistant是 UltraBot 中一切功能的基础。