OpenViking VikingBot HTTP API 实战指南：/bot/v1代理架构、Chat 与反馈接口详解
【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking
本指南以 OpenViking 仓库中文档 docs/zh/api/24-vikingbot.md 为骨架，系统讲解 VikingBot HTTP API 的使用方式与底层实现。你将掌握：openviking-server --with-bot如何把 VikingBot 核心交互能力暴露到/bot/v1，health、chat、chat/stream、feedback四个端点的请求/响应格式与参数语义，以及代理层的鉴权转发、图片校验和 SSE 事件流的工作机制，最终能独立把 Agent 对话能力接入自己的服务端程序。
一、Bot API 是什么：一个被 Server 代理的 Agent 交互入口
OpenViking 是面向 AI Agent 的上下文数据库（统一管理 Resource、Memory、Skill），VikingBot 则是接收用户消息、组织上下文、调用模型和工具、并交付结果的多渠道 Agent。两者组合后，Agent 不仅能完成任务，还能持续积累用户记忆、会话摘要和任务经验（参见 VikingBot 概念）。
要把这套能力以 HTTP 方式暴露给自定义客户端，就需要 VikingBot 的Bot API。它的关键特征有二：
- 必须显式启用：只有以
--with-bot参数启动 OpenViking Server 时，Server 才会在/bot/v1下代理 VikingBot 的核心交互接口；未启用 Bot 时，这些端点统一返回503。 - 代理而非直连：OpenViking Server 负责对浏览器/客户端请求做鉴权，再把身份注入转发给本地 VikingBot Gateway；Bot 工具调用必须沿用这一身份，而不是回退到 Gateway 自身的静态 root/user-key 配置。
从源码看，这一链路涉及三个核心模块：
- openviking/server/routers/bot.py：OpenViking Server 侧的代理路由与身份转发；
- bot/vikingbot/channels/openapi.py：VikingBot Gateway 侧的 OpenAPIChannel 路由实现（含 Session、Channel 与 OpenViking API 代理）；
- bot/vikingbot/channels/openapi_models.py：请求、响应和 SSE 事件的 Pydantic 模型与校验逻辑。
启用前提：--with-bot的启动链路
在 openviking/server/bootstrap.py 中，--with-bot参数会同时设置config.with_bot = True，并尝试拉起 VikingBot Gateway 子进程；openviking/server/config.py 中with_bot: bool = False是该项的默认值。启动后，openviking/server/app.py 会调用set_bot_api_url()与set_bot_api_key()，把 Gateway 地址（例如http://localhost:18791）和网关令牌注入代理路由；未启用时则记录 "Bot API proxy disabled"。
注意：
--with-bot依赖安装带 bot 依赖的 openviking 包（pip install "openviking[bot]"），且 Bot 在此模式下固定连接当前启动的 OpenViking Server，不读取bot.ov_server.server_url指向其他服务。安装与三种运行场景（一体启动、vikingbot chat本地调试、vikingbot gateway统一入口）详见 VikingBot 安装与配置。
代理层的状态码约定
代理实现 openviking/server/routers/bot.py 中有一套清晰的状态码约定：
| 场景 | 状态码 | 说明 |
|---|---|---|
未启用--with-bot | 503 | get_bot_url()抛出的 "Bot service not enabled" |
| 请求体不是合法 JSON | 400 | "Invalid JSON in request body" |
| 缺少可转发的 API Key | 401 | "Bot proxy requires a forwardable OpenViking API key" |
| 上游 Gateway 连接失败 | 502 | 连接错误或 Gateway 返回 5xx |
| Gateway 返回客户端错误 | 透传 | 4xx 原样透传给调用方 |
二、health()：快速探测 Bot Gateway 是否可用
health()用于检查 Bot Gateway 是否可用，是接入前的第一个探测点。
HTTP API
curl http://localhost:1933/bot/v1/health响应示例
{ "status": "healthy", "version": "0.1.0", "timestamp": "2026-07-24T09:00:00" }实现上，代理层会向 Gateway 的{bot_url}/bot/v1/health发起带 5 秒超时的转发请求（见 openviking/server/routers/bot.py 的health_check），而 Gateway 侧的健康检查返回status="healthy" if channel._running else "unhealthy"并携带 VikingBot 版本号（见 bot/vikingbot/channels/openapi.py 的health_check）。在指标验证场景中，curl http://127.0.0.1:30300/bot/v1/health返回200是开始后续 Chat/Feedback 链路验证的前提之一（参见 VikingBot 指标验证）。
三、chat()：发送文本与图片并获取完整回复
chat()是核心的同步对话端点：发送文本和/或图片，等待 Agent 的完整回复。session_id可省略，省略时 Gateway 会自动创建新会话。
请求字段
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
message | string | 条件必填 | "" | 用户文本；images为空时必填 |
images | array | 条件必填 | [] | 最多 4 个 OpenAI 风格的image_url；message为空时必填 |
session_id | string | 否 | 自动生成 | 继续已有会话时传入 |
context | array | 否 | null | 额外上下文消息，每项包含role和content |
need_reply | boolean | 否 | true | 是否需要 Bot 回复 |
disabled_tools | string[] | 否 | [] | 本次请求禁用的工具名 |
channel_id | string | 否 | null | 多 Channel 路由标识 |
从模型定义（bot/vikingbot/channels/openapi_models.py 的ChatRequest）看，message为空且images也为空时请求会被模型校验拒绝；context字段当前不被支持，传入非空值会直接返回校验错误。
纯文本请求
curl -X POST http://localhost:1933/bot/v1/chat \ -H "Content-Type: application/json" \ -H "X-API-Key: your-key" \ -d '{"message":"总结我的项目进展","session_id":"optional-session-id"}'带图片请求
图片可以使用模型可访问的 HTTPS URL，或内联 Base64 Data URL：
curl -X POST http://localhost:1933/bot/v1/chat \ -H "Content-Type: application/json" \ -H "X-API-Key: your-key" \ -d '{ "message": "描述这张图片", "images": [{ "type": "image_url", "image_url": { "url": "https://example.com/photo.png" } }] }'图片校验规则（源码级细节）
图片的合法性校验在 bot/vikingbot/channels/openapi_models.py 的_validate_chat_image_url中实现，规则如下：
- HTTPS URL：必须是绝对 HTTPS 地址且不能带用户名/密码凭据；Gateway 只校验 URL 结构，不会下载或检查远程资源，因此远程格式支持及相关错误由具体 provider 决定；
- 内联 Base64：支持 JPEG、PNG、GIF 和 WebP，解码后单张最大 10 MiB；内联 SVG 以及 MIME 签名不匹配的图片会被拒绝；
- 本地文件路径：一律被拒绝；
detail字段：可选值为auto、low、high，为获得最好的模型兼容性建议省略。
值得一提的防御细节：校验器会先通过魔数签名（PNG 头、JPEG\xff\xd8\xff、GIF 头、RIFF/WEBP 头）探测真实类型，再与声明的 MIME 比对；同时会在解码前先按 Base64 长度估算拒绝超大负载，避免大临时内存分配。相应的图片校验行为还有独立的单元测试覆盖（见 tests/unit/test_vikingbot_chat_images.py）。
CLI 等价命令
Bot 对话同样可以通过ovCLI 发起，内部走同一套 AgentLoop：
ov chat -m "总结我的项目进展"响应示例
{ "session_id": "session-id", "response_id": "response-id", "message": "这是当前项目进展摘要……", "events": null, "relevant_memories": null, "token_usage": { "prompt_tokens": 120, "completion_tokens": 42, "total_tokens": 162 }, "timestamp": "2026-07-24T09:00:00" }其中response_id是后续提交反馈时必须回传的关联凭证；token_usage给出本轮 prompt/completion/total 三档 token 统计。
四、chat_stream()：用 SSE 消费增量事件
chat_stream()以 Server-Sent Events 返回推理、工具调用、增量内容和最终响应事件。请求字段与chat()完全相同；Gateway 会自动启用流式模式（路由实现中if not request.stream: request.stream = True，见 bot/vikingbot/channels/openapi.py）。
HTTP API
curl -N -X POST http://localhost:1933/bot/v1/chat/stream \ -H "Content-Type: application/json" \ -H "X-API-Key: your-key" \ -d '{"message":"分析当前知识库"}'CLI
ov chat -m "分析当前知识库"SSE 响应示例
每条消息使用data: <json>格式，响应头X-VikingBot-Session-ID包含本次会话 ID。
data: {"event":"reasoning_delta","data":"正在检查知识库…","timestamp":"2026-07-24T09:00:00"} data: {"event":"content_delta","data":"当前知识库包含","timestamp":"2026-07-24T09:00:01"} data: {"event":"response","data":{"content":"当前知识库包含……","response_id":"response-id"},"timestamp":"2026-07-24T09:00:02"}event的可能取值与语义如下：
| event | 含义 |
|---|---|
reasoning | 整段推理开始 |
reasoning_delta | 推理增量片段 |
tool_call | 模型发起工具调用 |
tool_result | 工具执行结果 |
content_delta | 回复正文增量 |
iteration | 新一轮 Agent 迭代 |
response | 最终完整响应（携带content与response_id） |
这些事件与 VikingBot 消息总线中的OutboundEventType（RESPONSE、REASONING、CONTENT_DELTA、REASONING_DELTA、TOOL_CALL、TOOL_RESULT、ITERATION）一一对应（见 bot/vikingbot/channels/openapi.py 的send方法）。PendingResponse内部用asyncio.Queue把事件逐条推给 SSE 响应流。代理层（openviking/server/routers/bot.py 的chat_stream）则通过httpx流式读取上游并按块透传，同时设置Cache-Control: no-cache与Connection: keep-alive；若上游异常，会以{"event":"error",...}的 SSE 事件形式返回错误。测试 tests/server/test_bot_proxy_auth.py 中test_chat_stream_proxy_preserves_sse_event_boundaries专门验证了代理层不破坏 SSE 事件边界。
五、feedback()：为历史回复提交显式反馈
feedback()用于对已经生成的回复提交显式反馈，是 Agent 持续学习与指标评估闭环的关键一环。
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
session_id | string | 是 | 产生目标回复的会话 ID |
response_id | string | 是 | 目标助手回复 ID |
feedback_type | string | 是 | thumb_up、thumb_down或rating |
feedback_score | number | 条件必填 | feedback_type=rating时必须提供 |
feedback_reason | string | 否 | 反馈原因标签 |
feedback_text | string | 否 | 自由文本反馈 |
channel_id | string | 否 | 多 Channel 路由标识 |
从模型校验看（FeedbackRequest），rating类型缺少feedback_score时会直接返回请求校验错误（422）；response_id与session_id均不允许为空字符串。
HTTP API
curl -X POST http://localhost:1933/bot/v1/feedback \ -H "Content-Type: application/json" \ -H "X-API-Key: your-key" \ -d '{ "session_id":"session-id", "response_id":"response-id", "feedback_type":"thumb_up" }'响应示例
{ "accepted": true, "response_id": "response-id", "session_id": "session-id", "feedback_type": "thumb_up", "feedback_delay_sec": 8.42, "timestamp": "2026-07-24T09:00:08" }feedback_delay_sec表示从回复生成到提交反馈的间隔秒数。目标回复不存在时返回404。在 VikingBot 指标验证 中，thumb_up/thumb_down/rating反馈会被写入持久化 session 的metadata.feedback_events，随后由FeedbackCollector在 Prometheus 抓取/metrics时聚合成openviking_feedback_*系列指标（如openviking_feedback_thumb_up_total、openviking_feedback_negative_outcomes_total等），从而形成「提问 → Chat → 反馈 → 指标」的完整可观测链路。
六、鉴权与安全边界：代理如何保证"身份不错位"
Bot API 的安全模型值得专门说明，它由两层独立边界组成：
1. Gateway 入口层：X-Gateway-Token
VikingBot Gateway 侧通过verify_gateway_request校验请求（bot/vikingbot/channels/openapi.py）：
- Gateway 默认监听
127.0.0.1等 loopback 地址时，本地请求可免 token； - 当
host改为非 localhost 地址时，必须配置bot.gateway.token，且每次请求必须携带X-Gateway-Token头，否则返回401/403（用secrets.compare_digest做常量时间比较）； - 未配置 token 的非 localhost 部署会直接返回
503。
2. OpenViking 身份层：openviking_connection
OpenViking Server 代理在转发前，会把已鉴权的调用者身份包装为openviking_connection注入请求体（openviking/server/routers/bot.py 的_attach_openviking_connection），包含account_id、user_id、agent_id（默认web-playground）、role、api_key_type（trusted 模式为root，否则为user）、server_url以及可选的api_key。
Gateway 侧对openviking_connection有严格限制：只接受来自可信 Server 代理的注入（forwarded_connection_trusted，要求 loopback 请求且网关在 localhost 或 token 有效），否则返回403"openviking_connection is only accepted from trusted server proxy"。这样设计的目的正如源码注释所言：Bot 工具必须继续使用代理鉴权后的同一身份，而不是回退到 VikingBot 的静态 root/user-key 配置。此外，Gateway 还会周期性探测上游 OpenViking 的/health，校验auth_mode是否在启动后发生变更，避免信任边界漂移（_assert_runtime_health_mode）。
对外部客户端而言，标准用法是携带自己的 OpenViking API Key：
curl -X POST http://localhost:1933/bot/v1/chat \ -H "Content-Type: application/json" \ -H "X-API-Key: your-key" \ -d '{"message":"你好"}'X-API-Key与Authorization: Bearer <token>两种头均可被代理识别并转发（见_extract_forward_api_key）。代理鉴权行为有专门测试覆盖（tests/server/test_bot_proxy_auth.py），包括 trusted 模式下免 root key 的转发、X-Gateway-Token头透传、以及openviking_connection身份注入的字段断言。
七、客户端范围与扩展：SDK 边界、Session 与多 Channel
标准 OpenViking Python、TypeScript 和 Go SDK（分别见 sdk/python、sdk/typescript、sdk/go）当前不封装Bot 代理接口；Chat 可通过ovCLI 与 HTTP 两种方式使用。
如果你需要更完整的会话管理能力，VikingBot Gateway 自身还提供了额外的 HTTP 接口：
- Session API：
GET /bot/v1/sessions列会话、POST /bot/v1/sessions创建会话、GET /bot/v1/sessions/{session_id}查详情、DELETE /bot/v1/sessions/{session_id}删除会话（实现于 bot/vikingbot/channels/openapi.py 的_create_router）； - 多 Channel 路由：当配置了
type="bot_api"的 BotChannel（如channel_id="demo"）时，可以使用POST /bot/v1/chat/channel与POST /bot/v1/chat/channel/stream指定channel_id对话，未配置的 channel 返回404 Channel '<channel_id>' not found。这使同一 Gateway 能以type + channel_id + chat_id三元组隔离不同渠道实例和会话； - OpenViking API 代理：Gateway 还提供
GET/POST/PUT/PATCH/DELETE /api/v1/{path}透传 OpenViking API，配合bot.ov_server.server_url配置，可以让ovCLI 通过 Gateway 统一入口访问 Chat 与 OpenViking 命令（配置示例见 VikingBot 安装与配置 的场景 C）。
八、从文档到验证：一条可复现的接入路径
如果你想在本地把整条链路跑通并验证，可以按以下顺序进行：
- 安装并启动：
pip install "openviking[bot]"，执行openviking-server --with-bot（完整步骤见 VikingBot 安装与配置）； - 探测健康：
curl http://localhost:1933/bot/v1/health，确认返回200与"status": "healthy"； - 发起对话：调用
/bot/v1/chat发送首轮问题，从响应中记录session_id与response_id； - 流式体验：改用
/bot/v1/chat/stream观察reasoning_delta→content_delta→response的事件序列； - 提交反馈：用上一步的
response_id调用/bot/v1/feedback提交thumb_up/thumb_down； - 接入可观测：若启用了
server.observability.metrics.enabled=true与 Prometheus/Grafana，可按 VikingBot 指标验证 中的七个真实问答场景逐一验证openviking_feedback_*指标的阶梯变化，确认「提问 → Chat → 会话持久化 → 反馈 → 指标」全链路健康。
相关文档
- VikingBot 概念 —— 架构与 Agent 交互流程
- VikingBot 安装与配置 —— 三种运行场景、
ov.conf配置与 Gateway 部署 - VikingBot 指标验证 —— Chat、Feedback 与指标链路的真实问答验收
- 代理实现：openviking/server/routers/bot.py
- Gateway 路由：bot/vikingbot/channels/openapi.py
- 数据模型与校验：bot/vikingbot/channels/openapi_models.py
【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
