快速开始：服务端模式

将 OpenViking 作为独立 HTTP 服务运行，并从任意客户端连接。

前置要求

已安装 OpenViking（pip install openviking --upgrade --force-reinstall）
模型配置已就绪（参见快速开始了解配置方法）

启动服务

确保 ov.conf 已配置好存储路径和模型信息（参见快速开始），然后启动服务：

如果是首次配置，建议先运行 openviking-server init。

启动前建议先做本地校验：

bash

openviking-server doctor

openviking-server doctor 会校验当前本地配置是否可用，包括各 provider 需要的鉴权状态。

bash

# 配置文件在默认路径 ~/.openviking/ov.conf 时，直接启动
openviking-server

# 配置文件在其他位置时，通过 --config 指定
openviking-server --config /path/to/ov.conf

# 覆盖 host/port
openviking-server --port 1933

你应该看到：

INFO:     Uvicorn running on http://0.0.0.0:1933

验证

bash

curl http://localhost:1933/health
# {"status": "ok"}

openviking-server doctor 用于校验本地配置、模型访问和鉴权状态；curl /health 只表示服务进程已经启动。

使用 Python SDK 连接

python

import openviking as ov

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

启用认证

服务端启用认证后，需要传入 api_key。OpenViking 使用两层 API Key 体系，请根据场景选择：

常规数据访问：使用 user_key（推荐）

大多数场景应使用 user_key，可直接调用 add_resource、find、ls 等租户级 API：

python

import openviking as ov

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="<user-key>",
    agent_id="my-agent",      # 可选
)

user_key 通过 Admin API 创建（参见认证文档），服务端可自动识别其所属租户。

管理操作：使用 root_key

root_key 适用于管理操作（创建账户、系统状态等）。如需用 root_key 访问租户级 API，必须同时传入 account 和 user，否则服务端会拒绝请求：

python

import openviking as ov

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="<root-key>",
    account="acme",           # 必须：目标租户
    user="alice",             # 必须：目标用户
)

⚠️ 使用 root_key 调用 add_resource、find 等租户级 API 时，如果未提供 account/user，会收到： ROOT requests to tenant-scoped APIs must include X-OpenViking-Account and X-OpenViking-User headers

更多认证细节（trusted 模式、CLI 配置等）请参见认证文档。

完整示例（使用 user_key）：

python

import openviking as ov

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

try:
    client.initialize()

    # Add a resource
    result = client.add_resource(
        "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
    )
    root_uri = result["root_uri"]

    # Wait for processing
    client.wait_processed()

    # Search
    results = client.find("what is openviking", target_uri=root_uri)
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")

finally:
    client.close()

使用 CLI 连接

创建 CLI 连接配置文件 ~/.openviking/ovcli.conf：

json

{
  "url": "http://localhost:1933",
  "api_key": "your-key"
}

然后直接使用 CLI 命令：

bash

# Check system health
openviking observer system

# Add a resource to memory
openviking add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md

# List all synchronized resources
openviking ls viking://resources

# Query
openviking find "what is openviking"

如果配置文件在其他位置，通过环境变量指定：

bash

export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf

使用 curl 连接

远端 URL 可以直接放在 path 里。本地文件需要先调用 POST /api/v1/resources/temp_upload 上传，再用返回的 temp_file_id 调目标 API。裸 HTTP 如果导入本地目录，需要先把目录打成 .zip 再上传。

bash

# Add a resource
curl -X POST http://localhost:1933/api/v1/resources \
  -H "Content-Type: application/json" \
  -d '{"path": "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"}'

# List resources
curl "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/"

# Semantic search
curl -X POST http://localhost:1933/api/v1/search/find \
  -H "Content-Type: application/json" \
  -d '{"query": "what is openviking"}'

推荐云端部署方案：火山引擎 ECS

为了获得高性能、可扩展的 Context Memory 能力，能够像“长期记忆”一样为 Agent 提供支持，我们推荐使用 火山引擎云服务器 (ECS) 结合 veLinux 操作系统进行部署。

1. 实例采购配置

在火山引擎 ECS 控制台创建实例时，推荐以下配置：

配置项	推荐参数	说明
镜像	veLinux 2.0 (CentOS 兼容版)	勾选“安全加固”
规格	计算型 c3a (2 vCPU, 4GiB 或更高)	满足基础推理与检索需求
存储	添加数据盘 256 GiB	向量数据存储
网络	按需配置	建议仅放通所需业务端口 (eg. TCP 1933)

2. 系统环境准备（挂载数据盘）

实例启动后，需将数据盘挂载至 /data 目录。请在服务器执行以下命令，自动完成格式化与挂载：

bash

# 1. 创建挂载点
mkdir -p /data

# 2. 配置自动挂载 (使用 UUID 防止盘符漂移)
cp /etc/fstab /etc/fstab.bak
DISK_UUID=$(blkid -s UUID -o value /dev/vdb)

if [ -z "$DISK_UUID" ]; then
    echo "ERROR: /dev/vdb UUID not found"
else
    # 写入 fstab
    echo "UUID=${DISK_UUID} /data ext4 defaults,nofail 0 0" >> /etc/fstab
    # 验证并挂载
    mount -a
    echo "挂载成功，当前磁盘状态："
    df -Th /data
fi

3. 安装依赖及OpenViking

yum install -y curl git tree

# 第一步：安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 第二步：配置环境变量
echo 'source $HOME/.cargo/env' >> ~/.bashrc

# 配置生效
source ~/.bashrc

# 验证安装
uv --version

# 第三步：在数据盘创建虚拟环境
cd /data

# 创建名为 ovenv 的虚拟环境
uv venv ovenv --python 3.11

# 第四步：激活虚拟环境
source /data/ovenv/bin/activate

# 第五步：验证
echo "Ready"
echo "Python path: $(which python)"
echo "Python version: $(python --version)"

安装 OpenViking：在激活的虚拟环境下安装工具：

uv tool install openviking --upgrade

接下来就可以准备配置了。

4. OpenViking 服务端配置与启动

配置 AI 模型并让服务在后台常驻。

准备配置文件

在启动服务之前，先建立配置文件目录和文件。

创建配置目录：

mkdir -p ~/.openviking

创建并编辑配置文件：

vim ~/.openviking/ov.conf

配置文件内容可参考

{
  "embedding": {
    "dense": {
      "api_base" : "<api-endpoint>",   // API endpoint address (e.g., [https://ark.cn-beijing.volces.com/api/v3](https://ark.cn-beijing.volces.com/api/v3))
      "api_key"  : "<your-api-key>",   // Model service API Key
      "provider" : "<provider-type>",  // Provider type (volcengine or openai)
      "dimension": 1024,               // Vector dimension
      "model"    : "<model-name>",     // Embedding model name (e.g., doubao-embedding-vision-251215)
      "input"    : "multimodal"        // if use doubao-embedding-vision-251215, should be multimodal
    }
  },
  "vlm": {
    "api_base"   : "<api-endpoint>",     // API endpoint address (e.g., [https://ark.cn-beijing.volces.com/api/v3](https://ark.cn-beijing.volces.com/api/v3))
    "api_key"    : "<your-api-key>",     // Model service API Key
    "provider"   : "<provider-type>",    // Provider type (volcengine or openai)
    "max_retries": 2,
    "model"      : "<model-name>"        // VLM model name (e.g., doubao-seed-2-0-pro-260215 or gpt-4-vision-preview)
  }
}

进入 vim 后按 i 粘贴您的配置内容，完成后按 Esc 输入 :wq 保存退出。

后台启动服务：

我们将使用虚拟环境中的程序，并让它在后台运行。

激活虚拟环境

source /data/ovenv/bin/activate

mkdir -p /data/log/

后台启动并重定向输出：

nohup openviking-server > /data/log/openviking.log 2>&1 &

# 默认会以执行命令的路径下创建 ./data 存放数据
# 如果后续希望杀死服务进程记得要清理两个后台服务：pkill openviking; pkill agfs

可以看到服务在后台常驻运行。当然如果希望重启自动恢复，建议采用 systemctl 启动，此处不赘述。服务启动后，可以在 /data 下看到数据文件、日志文件等。

验证服务状态：

检查进程：输入以下命令查看程序是否在运行：

ps aux | grep openviking-server

查看日志：如果进程在，看看有没有报错：

tail -f /data/log/openviking.log # TODO 支持日志滚动

配置客户端并测试 (CLI)

本地注意也要先安装 openviking 才能使用 CLI 工具, 然后在 ovcli.conf 配置好服务端地址

准备客户端配置：

vim ~/.openviking/ovcli.conf

写入以下内容（注意 IP 换成您服务器的 IP地址）：

{
  "url": "http://XXX.XXX.XXX.XXX:1933",
  "api_key": "your-key"
}

执行系统观察命令，监控系统健康状态：

openviking observer system

功能测试（上传与查找）

# 上传测试文件
openviking add-resource https://raw.githubusercontent.com/ZaynJarvis/doc-eval/refs/heads/main/text.md

# 列出资源
openviking ls viking://resources

# 检索测试
openviking find "who is Alice"

下一步

服务部署 - 配置、认证和部署选项
API 概览 - 完整 API 参考
认证 - 使用 API Key 保护你的服务

快速开始：服务端模式 ​

前置要求 ​

启动服务 ​

验证 ​

使用 Python SDK 连接 ​

启用认证 ​

使用 CLI 连接 ​

使用 curl 连接 ​

推荐云端部署方案：火山引擎 ECS ​

1. 实例采购配置 ​

2. 系统环境准备（挂载数据盘） ​

3. 安装依赖及OpenViking ​

4. OpenViking 服务端配置与启动 ​

准备配置文件 ​

下一步 ​

快速开始：服务端模式

前置要求

启动服务

验证

使用 Python SDK 连接

启用认证

使用 CLI 连接

使用 curl 连接

推荐云端部署方案：火山引擎 ECS

1. 实例采购配置

2. 系统环境准备（挂载数据盘）

3. 安装依赖及OpenViking

4. OpenViking 服务端配置与启动

准备配置文件

下一步