OpenViking VikingBot HTTP API 实战指南：`/bot/v1` 代理架构、Chat 与反馈接口详解

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/v1health、chat、chat/stream、feedback四个端点的请求/响应格式与参数语义以及代理层的鉴权转发、图片校验和 SSE 事件流的工作机制最终能独立把 Agent 对话能力接入自己的服务端程序。一、Bot API 是什么一个被 Server 代理的 Agent 交互入口OpenViking 是面向 AI Agent 的上下文数据库统一管理 Resource、Memory、SkillVikingBot 则是接收用户消息、组织上下文、调用模型和工具、并交付结果的多渠道 Agent。两者组合后Agent 不仅能完成任务还能持续积累用户记忆、会话摘要和任务经验参见 VikingBot 概念。要把这套能力以 HTTP 方式暴露给自定义客户端就需要 VikingBot 的Bot API。它的关键特征有二必须显式启用只有以--with-bot参数启动 OpenViking Server 时Server 才会在/bot/v1下代理 VikingBot 的核心交互接口未启用 Bot 时这些端点统一返回503。代理而非直连OpenViking Server 负责对浏览器/客户端请求做鉴权再把身份注入转发给本地 VikingBot GatewayBot 工具调用必须沿用这一身份而不是回退到 Gateway 自身的静态 root/user-key 配置。从源码看这一链路涉及三个核心模块openviking/server/routers/bot.pyOpenViking Server 侧的代理路由与身份转发bot/vikingbot/channels/openapi.pyVikingBot 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-bot503get_bot_url()抛出的 Bot service not enabled请求体不是合法 JSON400Invalid JSON in request body缺少可转发的 API Key401Bot proxy requires a forwardable OpenViking API key上游 Gateway 连接失败502连接错误或 Gateway 返回 5xxGateway 返回客户端错误透传4xx 原样透传给调用方二、health()快速探测 Bot Gateway 是否可用health()用于检查 Bot Gateway 是否可用是接入前的第一个探测点。HTTP APIcurl 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 侧的健康检查返回statushealthy 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 会自动创建新会话。请求字段字段类型必填默认值说明messagestring条件必填用户文本images为空时必填imagesarray条件必填[]最多 4 个 OpenAI 风格的image_urlmessage为空时必填session_idstring否自动生成继续已有会话时传入contextarray否null额外上下文消息每项包含role和contentneed_replyboolean否true是否需要 Bot 回复disabled_toolsstring[]否[]本次请求禁用的工具名channel_idstring否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 URLcurl -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 发起内部走同一套 AgentLoopov 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 APIcurl -N -X POST http://localhost:1933/bot/v1/chat/stream \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d {message:分析当前知识库}CLIov 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 消息总线中的OutboundEventTypeRESPONSE、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_idstring是产生目标回复的会话 IDresponse_idstring是目标助手回复 IDfeedback_typestring是thumb_up、thumb_down或ratingfeedback_scorenumber条件必填feedback_typerating时必须提供feedback_reasonstring否反馈原因标签feedback_textstring否自由文本反馈channel_idstring否多 Channel 路由标识从模型校验看FeedbackRequestrating类型缺少feedback_score时会直接返回请求校验错误422response_id与session_id均不允许为空字符串。HTTP APIcurl -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-TokenVikingBot Gateway 侧通过verify_gateway_request校验请求bot/vikingbot/channels/openapi.pyGateway 默认监听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_connectionOpenViking Server 代理在转发前会把已鉴权的调用者身份包装为openviking_connection注入请求体openviking/server/routers/bot.py 的_attach_openviking_connection包含account_id、user_id、agent_id默认web-playground、role、api_key_typetrusted 模式为root否则为user、server_url以及可选的api_key。Gateway 侧对openviking_connection有严格限制只接受来自可信 Server 代理的注入forwarded_connection_trusted要求 loopback 请求且网关在 localhost 或 token 有效否则返回403openviking_connection is only accepted from trusted server proxy。这样设计的目的正如源码注释所言Bot 工具必须继续使用代理鉴权后的同一身份而不是回退到 VikingBot 的静态 root/user-key 配置。此外Gateway 还会周期性探测上游 OpenViking 的/health校验auth_mode是否在启动后发生变更避免信任边界漂移_assert_runtime_health_mode。对外部客户端而言标准用法是携带自己的 OpenViking API Keycurl -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 APIGET /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 路由当配置了typebot_api的 BotChannel如channel_iddemo时可以使用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.enabledtrue与 Prometheus/Grafana可按 VikingBot 指标验证 中的七个真实问答场景逐一验证openviking_feedback_*指标的阶梯变化确认「提问 → Chat → 会话持久化 → 反馈 → 指标」全链路健康。相关文档VikingBot 概念 —— 架构与 Agent 交互流程VikingBot 安装与配置 —— 三种运行场景、ov.conf配置与 Gateway 部署VikingBot 指标验证 —— Chat、Feedback 与指标链路的真实问答验收代理实现openviking/server/routers/bot.pyGateway 路由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），仅供参考