Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

6.8 KB
Raw Blame

VikingBot API

OpenViking Server 启用 --with-bot 后,会在 /bot/v1 下代理 VikingBot 的核心交互接口。未启用 Bot 时,这些端点返回 503。

代码入口:

  • openviking/server/routers/bot.py - OpenViking Server 代理与身份转发
  • bot/vikingbot/channels/openapi.py - VikingBot Gateway 路由实现
  • bot/vikingbot/channels/openapi_models.py - 请求、响应和 SSE 事件模型

API 参考

health()

检查 Bot Gateway 是否可用。

HTTP API

curl http://localhost:1933/bot/v1/health

响应示例

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-07-24T09:00:00"
}

chat()

发送文本和/或图片并等待完整回复。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 路由标识

HTTP API

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"
      }
    }]
  }'

内联 Base64 图片支持 JPEG、PNG、GIF 和 WebP,解码后单张最大 10 MiB;内联 SVG 和 MIME 签名不匹配的图片会被拒绝。对于 HTTPS URL,Gateway 只校验 URL 结构,不会下载或检查远程 资源,因此远程格式支持及相关错误由具体 provider 决定。本地文件路径仍会被拒绝。可选的 detail 支持 auto、low、high;为获得最好的模型兼容性,建议省略。

CLI

ov chat 默认通过 /chat/stream 流式输出。

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"
}

chat_stream()

以 Server-Sent Events 返回推理、工具调用、增量内容和最终响应事件。请求字段与 chat() 相同;Gateway 会自动启用流式模式。

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 可能为 reasoning、reasoning_delta、tool_call、tool_result、content_delta、iteration 或 response。

feedback()

对已经生成的回复提交显式反馈。

字段 类型 必填 说明
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 路由标识

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"
}

目标回复不存在时返回 404;rating 缺少 feedback_score 时返回请求校验错误。

interrupt_session()

中断活跃或排队中的 Bot 会话。OpenViking 会把已认证的 Account 和 User 身份转发给本地 VikingBot Gateway。

POST /bot/v1/sessions/{session_id}/interrupt

HTTP API

curl -X POST http://localhost:1933/bot/v1/sessions/session-id/interrupt \
  -H "X-API-Key: your-key"

响应示例

响应体由 VikingBot 透传;典型响应如下:

{
  "interrupted": true
}

steer_session()

向活跃的流式 Bot 会话追加用户输入。OpenViking 会丢弃客户端提交的 openviking_connection,并在转发前附加已认证的 OpenViking 连接信息。

POST /bot/v1/sessions/{session_id}/steer
Content-Type: application/json
字段 类型 必填 说明
message string 是 追加到活跃会话的用户输入
openviking_connection object 否 客户端传入时会被忽略;OpenViking 会附加已认证连接

HTTP API

curl -X POST http://localhost:1933/bot/v1/sessions/session-id/steer \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"message":"继续下一步"}'

响应示例

响应体由 VikingBot 透传;典型响应如下:

{
  "accepted": true
}

客户端范围

标准 OpenViking Python、TypeScript 和 Go SDK 当前不封装 Bot 代理接口;Chat 可通过 ov CLI 与 HTTP 使用。VikingBot Gateway 自身还提供 Session 和 Channel API,详见 VikingBot 文档。

相关文档