API 概览

本页介绍如何连接 OpenViking 以及所有 API 端点共享的约定。

连接 OpenViking

OpenViking 支持三种连接模式：

模式	使用场景	说明
嵌入式	本地开发，单进程	本地运行，数据存储在本地
HTTP	连接 OpenViking Server	通过 HTTP API 连接远程服务
CLI	Shell 脚本、Agent 工具调用	通过 CLI 命令连接服务端

嵌入式模式

python

import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

嵌入式模式通过 ov.conf 配置 embedding、vlm、storage 等模块。默认路径 ~/.openviking/ov.conf，也可通过环境变量指定：

bash

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

最小配置示例：

json

{
  "embedding": {
    "dense": {
      "api_base": "<api-endpoint>",
      "api_key": "<your-api-key>",
      "provider": "<volcengine|openai|jina|...>",
      "dimension": 1024,
      "model": "<model-name>"
    }
  },
  "vlm": {
    "api_base": "<api-endpoint>",
    "api_key": "<your-api-key>",
    "provider": "<volcengine|openai|openai-codex|kimi|glm>",
    "model": "<model-name>"
  }
}

当 provider: "openai-codex" 时，只要通过 openviking-server init 完成 Codex OAuth，就可以不填写 vlm.api_key。

完整配置选项和各服务商示例见配置指南。

HTTP 模式

python

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-key",
    agent_id="my-agent",
    timeout=120.0,
)
client.initialize()

未显式传入 url 时，HTTP 客户端会自动从 ovcli.conf 读取连接信息。ovcli.conf 是 HTTP 客户端和 CLI 共享的配置文件，默认路径 ~/.openviking/ovcli.conf，也可通过环境变量指定：

bash

export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf

json

{
  "url": "http://localhost:1933",
  "api_key": "your-key",
  "account": "acme",
  "user": "alice",
  "agent_id": "my-agent"
}

字段	说明	默认值
`url`	服务端地址	（必填）
`api_key`	API Key	`null`（无认证）
`account`	面向租户请求的默认 account 请求头	`null`
`user`	面向租户请求的默认 user 请求头	`null`
`agent_id`	Agent 标识符	`null`
`timeout`	HTTP 请求超时时间（秒）	`60.0`
`output`	默认输出格式：`"table"` 或 `"json"`	`"table"`

详见配置指南。

HTTP 模式下的本地文件

CLI、SyncHTTPClient、AsyncHTTPClient 遇到本地文件或目录时，会先自动上传，再调用服务端 API。
裸 HTTP 调用没有这层封装。使用 curl 或其他 HTTP 客户端时，需要先调用 POST /api/v1/resources/temp_upload，再把返回的 temp_file_id 传给目标 API。
裸 HTTP 如果导入本地目录，需要先自行打成 .zip 再上传；服务端不接受直接传宿主机目录路径。
POST /api/v1/resources 可以直接接收远端 URL，但不接受 ./doc.md、/tmp/doc.md 这类宿主机本地路径。

直接 HTTP（curl）

bash

curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
  -H "X-API-Key: your-key"

CLI 模式

CLI 连接到 OpenViking 服务端，将所有操作暴露为 Shell 命令。CLI 同样从 ovcli.conf 读取连接信息（与 HTTP 客户端共享）。

基本用法

bash

openviking [全局选项] <command> [参数] [命令选项]

全局选项（必须放在命令名之前）

选项	说明
`--output`, `-o`	输出格式：`table`（默认）、`json`
`--version`	显示 CLI 版本

示例：

bash

openviking -o json ls viking://resources/

生命周期

嵌入式模式

python

import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

# ... 使用 client ...

client.close()

HTTP 模式

python

import openviking as ov

client = ov.SyncHTTPClient(url="http://localhost:1933")
client.initialize()

# ... 使用 client ...

client.close()

认证

详见认证指南。

X-API-Key 请求头：X-API-Key: your-key
Bearer 请求头：Authorization: Bearer your-key
如果服务端未配置 API Key，则跳过认证。
/health 端点始终不需要认证。

响应格式

所有 HTTP API 响应遵循统一格式：

成功

json

{
  "status": "ok",
  "result": { ... },
  "time": 0.123
}

顶层 status 表示本次 HTTP API 请求是否成功。某些成功响应会在 result 中返回业务状态，例如 "status": "success"、"status": "accepted" 或任务状态。这些字段不是 API 传输层错误。

错误

json

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found: viking://resources/nonexistent/"
  },
  "time": 0.01
}

HTTP 错误始终使用顶层错误 envelope。资源解析、同步 reindex 等同步处理失败会返回非 2xx 响应，顶层为 status="error"，并包含 error 对象。客户端不应通过 result.status="error" 判断请求失败。

请求校验失败，包括 JSON 格式错误、缺少必填字段和参数值非法，统一返回 HTTP 400，并使用 error.code="INVALID_ARGUMENT"。响应不会使用 FastAPI 原生的 {"detail": ...} 错误格式；当存在字段级校验信息时，会通过 error.details.validation_errors 返回。

Python HTTP SDK（SyncHTTPClient 和 AsyncHTTPClient）会把该 envelope 映射为对应的 OpenVikingError 子类。例如 PROCESSING_ERROR 会抛出 ProcessingError。

CLI 输出格式

Table 模式（默认）

列表数据渲染为表格，非列表数据 fallback 到格式化 JSON：

bash

openviking ls viking://resources/
# name          size  mode  isDir  uri
# .abstract.md  100   420   False  viking://resources/.abstract.md

JSON 模式（`--output json`）

所有命令输出格式化 JSON，与 API 响应的 result 结构一致：

bash

openviking -o json ls viking://resources/
# [{ "name": "...", "size": 100, ... }, ...]

可在 ovcli.conf 中设置默认输出格式：

json

{
  "url": "http://localhost:1933",
  "output": "json"
}

紧凑模式（`--compact`, `-c`）

当 --output=json 时：紧凑 JSON 格式 + {ok, result} 包装，适用于脚本
当 --output=table 时：对表格输出采取精简表示（如去除空列等）

JSON 输出 - 成功

json

{"ok": true, "result": ...}

JSON 输出 - 错误

json

{"ok": false, "error": {"code": "NOT_FOUND", "message": "Resource not found", "details": {}}}

特殊情况

字符串结果（read、abstract、overview）：直接打印原文
None 结果（mkdir、rm、mv）：无输出

退出码

退出码	含义
0	成功
1	一般错误
2	配置错误
3	连接错误

错误码

错误码	HTTP 状态码	说明
`OK`	200	成功
`INVALID_ARGUMENT`	400	无效参数
`INVALID_URI`	400	无效的 Viking URI 格式
`NOT_FOUND`	404	资源未找到
`ALREADY_EXISTS`	409	资源已存在
`UNAUTHENTICATED`	401	缺少或无效的 API Key
`PERMISSION_DENIED`	403	权限不足
`RESOURCE_EXHAUSTED`	429	超出速率限制
`FAILED_PRECONDITION`	412	前置条件不满足
`CONFLICT`	409	操作与正在进行的任务或已有状态冲突
`DEADLINE_EXCEEDED`	504	操作超时
`UNAVAILABLE`	503	服务不可用
`PROCESSING_ERROR`	500	资源或语义处理失败
`INTERNAL`	500	内部服务器错误
`UNIMPLEMENTED`	501	功能未实现
`EMBEDDING_FAILED`	500	Embedding 生成失败
`VLM_FAILED`	500	VLM 调用失败
`SESSION_EXPIRED`	410	会话已过期

API 端点

系统

方法	路径	说明
GET	`/health`	健康检查（无需认证）
GET	`/ready`	就绪探针（无需认证）
GET	`/metrics`	Prometheus 指标导出
GET	`/api/v1/system/status`	系统状态
POST	`/api/v1/system/wait`	等待处理完成

资源

方法	路径	说明
POST	`/api/v1/resources/temp_upload`	裸 HTTP 导入资源 / pack 时上传本地文件
POST	`/api/v1/resources`	添加资源
POST	`/api/v1/skills`	添加技能
POST	`/api/v1/pack/export`	导出 .ovpack
POST	`/api/v1/pack/import`	导入 .ovpack

文件系统

方法	路径	说明
GET	`/api/v1/fs/ls`	列出目录
GET	`/api/v1/fs/tree`	目录树
GET	`/api/v1/fs/stat`	资源状态
POST	`/api/v1/fs/mkdir`	创建目录
DELETE	`/api/v1/fs`	删除资源
POST	`/api/v1/fs/mv`	移动资源

内容

方法	路径	说明
GET	`/api/v1/content/read`	读取完整内容（L2）
GET	`/api/v1/content/abstract`	读取摘要（L0）
GET	`/api/v1/content/overview`	读取概览（L1）
GET	`/api/v1/content/download`	下载原始文件字节流
POST	`/api/v1/content/write`	修改已有文件并自动刷新语义与向量
POST	`/api/v1/content/reindex`	重新构建已有内容的语义/向量索引

搜索

方法	路径	说明
POST	`/api/v1/search/find`	语义搜索
POST	`/api/v1/search/search`	上下文感知搜索
POST	`/api/v1/search/grep`	模式搜索
POST	`/api/v1/search/glob`	文件模式匹配

关联

方法	路径	说明
GET	`/api/v1/relations`	获取关联
POST	`/api/v1/relations/link`	创建链接
DELETE	`/api/v1/relations/link`	删除链接

会话

方法	路径	说明
POST	`/api/v1/sessions`	创建会话
GET	`/api/v1/sessions`	列出会话
GET	`/api/v1/sessions/{id}`	获取会话
GET	`/api/v1/sessions/{id}/context`	获取组装后的会话上下文
DELETE	`/api/v1/sessions/{id}`	删除会话
POST	`/api/v1/sessions/{id}/commit`	提交会话
POST	`/api/v1/sessions/{id}/extract`	从会话提取记忆
POST	`/api/v1/sessions/{id}/messages`	添加消息
POST	`/api/v1/sessions/{id}/used`	记录实际使用的上下文 / 技能
GET	`/api/v1/sessions/{id}/archives/{archive_id}`	获取特定会话归档

任务

方法	路径	说明
GET	`/api/v1/tasks/{task_id}`	获取后台任务状态
GET	`/api/v1/tasks`	列出后台任务

Observer

方法	路径	说明
GET	`/api/v1/observer/queue`	队列状态
GET	`/api/v1/observer/vikingdb`	VikingDB 状态
GET	`/api/v1/observer/models`	模型状态（VLM / embedding / rerank）
GET	`/api/v1/observer/lock`	锁子系统状态
GET	`/api/v1/observer/retrieval`	检索子系统状态
GET	`/api/v1/observer/system`	系统状态

调试

方法	路径	说明
GET	`/api/v1/debug/health`	快速健康检查
GET	`/api/v1/debug/vector/scroll`	分页查看向量记录
GET	`/api/v1/debug/vector/count`	统计向量记录数量

管理员（多租户）

方法	路径	说明
POST	`/api/v1/admin/accounts`	创建工作区 + 首个 admin（ROOT）
GET	`/api/v1/admin/accounts`	列出工作区（ROOT）
DELETE	`/api/v1/admin/accounts/{account_id}`	删除工作区（ROOT）
POST	`/api/v1/admin/accounts/{account_id}/users`	注册用户（ROOT, ADMIN）
GET	`/api/v1/admin/accounts/{account_id}/users`	列出用户（ROOT, ADMIN）
DELETE	`/api/v1/admin/accounts/{account_id}/users/{user_id}`	移除用户（ROOT, ADMIN）
PUT	`/api/v1/admin/accounts/{account_id}/users/{user_id}/role`	修改用户角色（ROOT）
POST	`/api/v1/admin/accounts/{account_id}/users/{user_id}/key`	重新生成 User Key（ROOT, ADMIN）

API 概览 ​

连接 OpenViking ​

嵌入式模式 ​

HTTP 模式 ​

直接 HTTP（curl） ​

CLI 模式 ​

生命周期 ​

认证 ​

响应格式 ​

CLI 输出格式 ​

Table 模式（默认） ​

JSON 模式（--output json） ​

紧凑模式（--compact, -c） ​

特殊情况 ​

退出码 ​

错误码 ​

API 端点 ​

系统 ​

资源 ​

文件系统 ​

内容 ​

搜索 ​

关联 ​

会话 ​

任务 ​

Observer ​

调试 ​

管理员（多租户） ​

相关文档 ​

API 概览

连接 OpenViking

嵌入式模式

HTTP 模式

直接 HTTP（curl）

CLI 模式

生命周期

认证

响应格式

CLI 输出格式

Table 模式（默认）

JSON 模式（`--output json`）

紧凑模式（`--compact`, `-c`）

特殊情况

退出码

错误码

API 端点

系统

资源

文件系统

内容

搜索

关联

会话

任务

Observer

调试

管理员（多租户）

相关文档