Nanobot OpenAI 兼容 API 完整指南:用 /v1/chat/completions 把本地 Agent 接入任何应用

发布时间:2026/9/18 15:17:26

Nanobot OpenAI 兼容 API 完整指南:用 /v1/chat/completions 把本地 Agent 接入任何应用 Nanobot OpenAI 兼容 API 完整指南用 /v1/chat/completions 把本地 Agent 接入任何应用【免费下载链接】nanobotUltra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps项目地址: https://gitcode.com/gh_mirrors/nanob/nanobotNanobot 内置了一套极简的 OpenAI 兼容 HTTP 服务以标准POST /v1/chat/completions端点对外暴露本地 Agent 能力任何会调 OpenAI API 的工具、脚本或 SDK如openaiPython 客户端、curl都能直接接入。本文以 docs/openai-api.md 为主线结合 API 服务实现、配置模型 与 命令入口 等源码完整讲解启动方式、鉴权策略、会话隔离、流式响应与文件上传读完即可将 nanobot 当作本地私有的 OpenAI 兼容推理服务使用。快速启动三条命令把 Agent 变成 APIAPI 服务由nanobot serve命令拉起完整的最小启动流程如下# 1. 启用 api 插件安装 aiohttp 依赖 nanobot plugins enable api # 2. CLI 冒烟测试确认 provider 与配置可用 nanobot agent -m Hello! # 3. 启动 OpenAI 兼容 API 服务器 nanobot serve第二步不是可选动作而是建议的排障前置如果nanobot agent -m Hello!失败先修复 provider 或配置再排查 API 服务器避免把配置问题误判为服务问题。nanobot serve启动时若缺少aiohttp会提示aiohttp is required. Install with: nanobot plugins enable api见 命令实现因此第一步是硬性前提。服务默认只绑定在回环地址127.0.0.1:8900改动config.json的api段即可调整。启动后控制台会打印端点、模型、默认会话与超时信息Endpoint : http://127.0.0.1:8900/v1/chat/completions Model : 当前模型名 Session : api:default Timeout : 120snanobot serve还接受多个命令行覆盖项定义见 serve 命令参数简写说明--port/-p端口默认取配置api.port8900--host/-H绑定地址默认取配置api.host127.0.0.1--timeout/-t单请求超时秒数默认取配置api.timeout120.0--verbose/-v显示 nanobot 运行时日志--workspace/-w工作区目录--config/-c配置文件路径命令行参数优先于config.json中的对应配置。此外WebUI 也内置了对该 API 进程的后台管理能力见 API 运行时管理通过run/与logs/目录隔离状态与日志。服务端构建链路从源码看nanobot serve的组装路径清晰可循commands.py从运行时配置取出api段host / port / timeout / apiKey构建MessageBus、SessionManager、ToolRegistry与MCPProvider用AgentLoop.from_config创建会话循环并把 MCP 连接作为每次请求前的prepare_agent回调调用create_app(agent_loop, model_name..., request_timeout..., api_key..., prepare_agentmcp_provider.connect)生成 aiohttp 应用并运行。也就是说每个 HTTP 请求最终都会进入AgentLoop.process_direct以channelapi、chat_iddefault的身份走一遍完整的 Agent 循环工具调用、MCP、记忆等能力全部可用核心实现在 loop.py。认证本机免密对外强制仅本机127.0.0.1使用时无需 API Key。若把api.host改为0.0.0.0或::对外网卡则必须配置api.apiKey否则启动直接失败——这是配置校验层强制执行的ApiConfig的校验器会在 host 为非回环地址而api_key为空时抛错见 schema.pynanobot serve启动路径同样会拦截commands.py。这样设计是为了避免把未鉴权的 Agent 端点暴露到网络上。{ api: { host: 0.0.0.0, port: 8900, apiKey: ${NANOBOT_API_KEY} } }apiKey支持环境变量插值如上例引用$NANOBOT_API_KEY。设置后所有 API 路由/v1/chat/completions、/v1/models都要求携带 Bearer Tokencurl http://127.0.0.1:8900/v1/models \ -H Authorization: Bearer $NANOBOT_API_KEY底层实现是一个 aiohttp 中间件server.py/health永远放行保证本地探活与负载均衡检查不受影响api_key为空时全部放行本机模式否则校验Authorization: Bearer key用hmac.compare_digest做常数时间比较缺失或错误均返回401。ApiConfig的完整字段schema.pyhost默认127.0.0.1、port默认8900、timeout默认120.0秒单请求超时、api_key默认空。行为约定会话隔离、单消息、固定模型API 服务的运行语义在 docs/openai-api.md 的 Behavior 一节有明确定义要点如下会话隔离请求体中传session_id可隔离不同对话不传则共享默认会话api:default。源码中会话键构造为session_key fapi:{session_id} if session_id else API_SESSION_KEYAPI_SESSION_KEY api:defaultserver.py。每个会话键都有独立的asyncio.Lock同会话请求串行执行不同会话可并行。单条 user 消息每个请求的messages数组必须恰好包含一条role: user消息。解析器_parse_json_content对非列表、长度不等于 1、非 user 角色等情况一律返回400 Only a single user message is supportedserver.py。固定模型model字段可省略或传入与GET /v1/models返回一致的模型名。传入其他模型名会得到400 Only configured model name is availableserver.py。/v1/models始终只返回当前配置的这一个模型handle_models。流式/非流式streamtrue时返回text/event-streamSSE以 OpenAI 兼容的增量 chunk 推送data: [DONE]收尾省略或streamfalse时返回单个 JSON 响应。请求超时单个请求默认 120 秒可由api.timeout或--timeout调整超时返回504 Request timed out after nsserver.py。跨渠道投递API 会话如何触达其他平台API 请求运行在合成的api渠道中因此message工具不会自动把消息投递到 Telegram / Discord 等平台。若要从 API 会话主动发消息到某个已启用渠道需要显式指定channel与chat_id{ content: Build finished successfully., channel: telegram, chat_id: 123456789 }注意如果channel指向的渠道未在配置中启用nanobot 只会把出站事件放入队列不会真正产生平台投递。响应结构非流式响应的 JSON 结构与 OpenAI 一致server.py{ id: chatcmpl-xxxxxxxxxxxx, object: chat.completion, created: 1726..., model: model, choices: [ { index: 0, message: {role: assistant, content: ...}, finish_reason: stop } ], usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 } }usage由内部_UsageCaptureHook从一次运行的LLMUsage聚合而来server.py若 Agent 返回空回复会回退为EMPTY_FINAL_RESPONSE_MESSAGE占位server.py。端点清单API 服务只暴露三个路由create_app 注册方法路径说明GET/health健康检查无需认证返回{status: ok}GET/v1/models列出当前模型POST/v1/chat/completions对话补全支持 JSON 与 multipart 两种请求体基础调用curl最简单的 JSON 调用curl http://127.0.0.1:8900/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [{role: user, content: hi}], session_id: my-session }session_id可选传入即隔离到独立会话省略则走默认会话api:default。文件上传JSON base64图片支持 OpenAI 多模态消息格式把图片以 base64 data URL 内联发送对应解析逻辑见 server.pycurl http://127.0.0.1:8900/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [{role: user, content: [ {type: text, text: Describe this image}, {type: image_url, image_url: {url: data:image/png;base64,iVBOR...}} ]}] }几点实现细节值得注意只接受以data:开头的 base64 data URL远端图片 URLhttp/https不被支持会返回400 Remote image URLs are not supported...需要改用 multipart 上传server.pybase64 解码与落盘由共享工具 media_decode.py 完成文件按 MIME 类型映射扩展名并存入api渠道的媒体目录aiohttp 应用把client_max_size设为 20MB给 base64 图片留出编解码余量server.py。文件上传multipart/form-data任意支持类型支持图片、PDF、Word、Excel、PPT 等文件通过multipart/form-data上传# 单文件 curl http://127.0.0.1:8900/v1/chat/completions \ -F messageSummarize this report \ -F filesreport.docx # 多文件 会话隔离 curl http://127.0.0.1:8900/v1/chat/completions \ -F messageCompare these files \ -F fileschart.png \ -F filesdata.xlsx \ -F session_idmy-session表单字段约定解析实现在 server.py字段说明message用户指令文本files文件内容可重复出现以提交多个文件session_id可选会话隔离model可选模型名需与配置一致若message为空服务端会回退为默认提示文本请分析上传的文件。单文件上限 10MBMAX_FILE_SIZE 10 * 1024 * 1024见 media_decode.py超限返回413。支持的文件类型落盘后由 Agent 侧按类型处理图片PNG、JPEG、GIF、WebP —— 以 base64 形式交给模型做视觉分析文档PDF、Word.docx、Excel.xlsx、PowerPoint.pptx—— 提取文本后交给模型文本TXT、Markdown、CSV、JSON 等 —— 直接读取。对应 MIME→扩展名映射可在 media_decode.py 中核对其中显式覆盖了application/pdf、application/json、text/csv、text/markdown以及 docx/xlsx/pptx 等常见类型。Python 客户端接入用requests直连不依赖任何 OpenAI SDK最直接的接入方式import requests resp requests.post( http://127.0.0.1:8900/v1/chat/completions, json{ messages: [{role: user, content: hi}], session_id: my-session, # 可选隔离会话 }, timeout120, ) resp.raise_for_status() print(resp.json()[choices][0][message][content])注意把timeout设得足够大默认请求超时 120s见api.timeout避免长任务被客户端侧提前掐断。用官方openaiSDK由于端点完全兼容 OpenAI 协议可以直接复用官方openaiPython 库把base_url指向本地from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8900/v1, api_keydummy, ) resp client.chat.completions.create( modelMiniMax-M2.7, messages[{role: user, content: hi}], extra_body{session_id: my-session}, # 可选隔离会话 ) print(resp.choices[0].message.content)api_key传占位值即可本机模式下服务端不校验。session_id是 nanobot 的扩展字段通过extra_body透传模型名需要与/v1/models返回一致。流式响应SSE设置streamtrue即可获得 OpenAI 风格的流式增量输出。服务端实现server.py会把 Agent 循环的流式 token 通过队列转发为 SSE chunkcurl http://127.0.0.1:8900/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [{role: user, content: hi}], stream: true }响应特征内容类型为text/event-stream带Cache-Control: no-cache每个 chunk 形如data: {id: chatcmpl-..., object: chat.completion.chunk, ...}同一流内 chunk 共享同一 id结束时先发送finish_reason: stop的空 delta chunk再发送data: [DONE]终止中间由工具调用产生的分段on_stream_end不会提前关闭 SSE 流整个 HTTP 流只在process_direct返回后关闭——这一行为在测试 tests/test_api_stream.py 中有专门用例覆盖如test_stream_segment_end_does_not_close_sse。流式行为相关的测试还包括streamtrue返回 SSE、streamfalse与缺省均返回 JSON、api_key鉴权、chunk id 一致性、on_stream回调透传等见 tests/test_api_stream.py。排障速查现象原因与处理nanobot agent -m Hello!失败先修复 provider/配置再启动 API 服务参考 quick-start.md、providers.md 与 troubleshooting.md启动报aiohttp is required执行nanobot plugins enable api安装依赖非回环 host 启动失败未设置api.apiKey配置apiKey后再启动传入其他模型名被拒只接受/v1/models列出的当前配置模型多消息数组被拒每次请求只支持一条user消息上传超过 10MB单文件上限 10MB超限返回 413远端图片 URL 被拒改用 base64 data URL 或 multipart 上传适用场景小结这个 API 端点的典型用途包括把 nanobot 接入已有聊天应用或工作流工具任何能发 HTTP 请求的客户端、为脚本提供带工具与记忆能力的对话后端、在局域网内搭建私有的 OpenAI 兼容服务配合apiKey鉴权、以及用官方openaiSDK 无痛迁移到本地 Agent。由于请求走完整 Agent 循环工具调用、MCP、记忆等能力与 WebUI / 聊天渠道完全一致只是换了一个api渠道的入口。更进一步该 API 也可作为“Agent 的 Agent”基础纳管 OpenAI 兼容端点即可由上层编排系统统一调度相关思路可参考 openai-compatible-agent-api.md。若需要更大规模的对外服务deploy-nanobot-gateway.md 介绍了网关部署形态可作为扩展阅读。【免费下载链接】nanobotUltra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps项目地址: https://gitcode.com/gh_mirrors/nanob/nanobot创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/18 15:17:26

MiMo 模型实测:这次用 TaoToken 走通快慢思考 API 调用

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/18 15:17:26

elasticsearch-head 部署、跨域与分片可视化实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/18 15:17:26

RTOS优先级反转导致机器人卡顿?调度与互斥量修复实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/18 16:17:34

Hadoop大数据可视化分析:从HDFS到ECharts的完整实现

简介:这是一份面向计算机科学与技术、软件工程等专业本科专科毕业生的原创学士学位论文,以Hadoop分布式计算框架为核心,系统探讨大数据可视化分析的实现与应用路径,适合需要完成毕业论文或希望入门大数据处理的学习者参考。压缩包…

2026/9/18 16:17:34

新版城市用地分类标准解析:城乡用地与建设用地编码及控规要点

简介:一份关于新版城市用地分类与规划建设用地标准的规范性资料,适用于城市规划、国土空间规划及相关专业师生和从业人员,用于理解城乡建设用地的分类体系、指标口径与规划编制要求。资源为1个doc文档,压缩包约211KB,内…

2026/9/18 16:17:34

智慧园区建设指南:三个平台一个中心与大数据实战

简介:这份《2021年智慧产业园区解决方案》PPT面向智慧城市行业1-3年的需求分析师与产品人员,系统梳理了物联网、云计算、大数据和人工智能等技术在园区建设中的落地路径。资源包共1个pptx文件,大小10.56MB,内容以架构图和方案设计…

2026/9/18 14:13:01

拯救者Y7000黑屏故障排查与维修实战指南

1. 项目概述:一台黑屏的拯救者Y7000,到底卡在哪一步? 联想拯救者Y7000系列笔记本,从2018年第一代搭载i5-8300H开始,到后来的i7-9750H、i7-10750H、i5-11400H,再到2023年款的R7-7840HS,它始终是学…

2026/9/18 0:01:09

Google Colab 实战:运行模型、数据加载与报错排查

1. 为什么我劝你先搞懂 Colab 的运行模型1.1 Colab 到底是什么,跟本地跑代码差在哪Google Colab 简单说就是一台跑在浏览器里的 Linux 虚拟机,你打开一个 Notebook,背后就连上了一台带 GPU 的远程机器。你在单元格里敲的每一行 Python&#x…

2026/9/18 0:01:09

C语言数据类型与表达式详解

1. C语言数据与数据类型概述在C语言编程中,数据是程序处理的核心对象。理解数据的分类和特性是掌握C语言的基础。C语言中的数据主要分为四大类:常量、变量、表达式和函数。这些数据类型构成了C语言程序的基本元素,每种类型都有其独特的特性和…

2026/9/18 0:01:09

SQL时间字段指定时间段查询:区间语义、索引与时区避坑

上周排查一个线上问题&#xff0c;用户反馈"昨天的订单一条都没查到"&#xff0c;但数据库里明明躺着两千多条。最后定位下来&#xff0c;不是数据丢了&#xff0c;也不是接口挂了&#xff0c;而是那个查询条件把时间段写成了> 2024-05-20 00:00:00 AND < 2024…

2026/9/18 14:13:03

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行&#xff0c;Type-C接口算是典型的“看着简单&#xff0c;做起来全坑”的东西。光引脚就24个&#xff0c;高低速信号、电源、控制线全部塞在一个小小的连接器里&#xff0c;如果PCB布局不做规划&#xff0c;打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/18 14:13:02

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/18 14:13:02

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码