OpenViking 本地搭建指南

OpenViking 本地搭建指南

目录

1. 环境依赖检查
2. [Python 依赖安装](#Python 依赖安装)
3. [Rust 组件编译](#Rust 组件编译)
4. 配置文件设置
5. 服务器启动与验证
6. 开发模式与生产模式
7. 参考文档

---

1. 环境依赖检查

必需依赖

依赖	最低版本	检查命令
Python	3.10+	python3 --version
Rust	1.91.1+	rustc --version
Cargo	与 Rust 配套	cargo --version
CMake	3.12+	cmake --version
Clang/GCC	11+/9+	clang++ --version / g++ --version

一键检查脚本

cd /Users/citi/dev/OpenViking && make check-deps

检查结果示例：

Checking dependencies...
  [OK] Python 3.13.5
  [OK] CMake 4.3.2
  [OK] Rust 1.95.0
  [OK] Clang 17.0.0

---

2. Python 依赖安装

基础安装

# 使用 uv 安装（推荐）
uv pip install -e "."

# 使用 pip 安装（备选）
pip install -e "."

开发依赖

# 安装开发依赖
uv pip install -e ".[dev]"

# 安装测试依赖
uv pip install -e ".[test]"

# 安装完整依赖（包含 bot）
uv pip install -e ".[bot,dev]"

---

3. Rust 组件编译

3.1 编译 ragfs-python（RAGFS Python 绑定）

# 进入 ragfs-python 目录
cd crates/ragfs-python

# 安装 maturin（如果未安装）
pip install maturin

# 编译并构建 wheel
maturin build --release --features s3 --out /tmp/ragfs_build

# 创建 lib 目录并提取 .so 文件
mkdir -p /Users/citi/dev/OpenViking/openviking/lib
unzip -j /tmp/ragfs_build/*.whl ragfs_python/*.so -d /Users/citi/dev/OpenViking/openviking/lib/

# 验证
ls -la /Users/citi/dev/OpenViking/openviking/lib/

3.2 编译 ov CLI（命令行工具）

cd /Users/citi/dev/OpenViking

# 编译 CLI
cargo build --release -p ov_cli

# 创建 bin 目录并复制可执行文件
mkdir -p openviking/bin
cp target/release/ov openviking/bin/

# 验证
ls -la openviking/bin/

---

4. 配置文件设置

4.1 配置文件位置

方式	路径	说明
默认	~/.openviking/ov.conf	自动查找
环境变量	OPENVIKING_CONFIG_FILE	手动指定路径
命令行参数	--config	临时指定

4.2 配置文件示例

{
  "storage": {
    "workspace": "/Users/citi/dev/OpenViking/workspace"
  },
  "log": {
    "level": "DEBUG",
    "output": "stdout"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 1933,
    "auth_mode": "dev"
  },
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "your-volcengine-api-key",
      "provider": "volcengine",
      "dimension": 1024,
      "model": "doubao-embedding-vision-251215"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "your-volcengine-api-key",
    "provider": "volcengine",
    "model": "doubao-seed-2-0-pro-260215",
    "max_concurrent": 100
  }
}

4.3 配置项说明

storage（存储配置）

字段	说明	默认值
workspace	工作空间目录	~/.openviking/data

log（日志配置）

字段	说明	默认值
level	日志级别	INFO
output	输出位置	stdout

server（服务器配置）

字段	说明	默认值
host	绑定地址	127.0.0.1
port	监听端口	1933
auth_mode	认证模式	dev

embedding（嵌入模型配置）

字段	说明
api_base	API 端点地址
api_key	API Key
provider	提供商（volcengine/openai/azure/litellm）
dimension	向量维度
model	模型名称

vlm（视觉语言模型配置）

字段	说明
api_base	API 端点地址
api_key	API Key
provider	提供商（volcengine/openai/azure/litellm）
model	模型名称

---

5. 服务器启动与验证

5.1 启动命令

# 基础启动（使用默认配置）
openviking-server

# 指定配置文件
# 1. 启动 OpenViking Server
cd /Users/citi/dev/OpenViking
openviking-server --config /Users/citi/dev/OpenViking/examples/ov.local.conf

# 2. 新开一个终端，启动 Console
cd /Users/citi/dev/OpenViking
python -m openviking.console.bootstrap \
  --host 127.0.0.1 \
  --port 8020 \
  --openviking-url http://127.0.0.1:1933 \
  --write-enabled

# 指定端口和主机
openviking-server --host 127.0.0.1 --port 1933

# 带 Bot 网关启动
openviking-server --with-bot

5.2 配置检测

openviking-server doctor

检测结果示例：

OpenViking Doctor

  Config:        PASS  /Users/citi/.openviking/ov.conf
  Python:        PASS  3.13.5 (>= 3.10 required)
  Native Engine: PASS  variant=x86_avx2
  AGFS:          PASS  AGFS SDK 0.1.7
  Embedding:     PASS  volcengine/doubao-embedding-vision-251215
  VLM:           PASS  volcengine/doubao-seed-2-0-pro-260215
  Ollama:        PASS  not configured
  Disk:          PASS  338.3 GB free

  All checks passed.

5.3 健康检查

curl http://127.0.0.1:1933/health

响应示例：

{
  "status": "ok",
  "healthy": true,
  "version": "0.3.9",
  "auth_mode": "dev",
  "account_id": "default",
  "user_id": "default",
  "agent_id": "default",
  "role": "root"
}

5.4 CLI 操作

# 查看状态
ov status

# 添加资源
ov add-resource https://github.com/volcengine/OpenViking

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

# 搜索
ov find "what is openviking"

---

6. 开发模式与生产模式

6.1 模式对比

模式	auth_mode	用途	安全性
开发模式	dev	本地开发测试	仅 localhost，无需认证
生产模式	api_key	对外服务	需要 API Key 认证

6.2 生产模式配置

{
  "server": {
    "host": "0.0.0.0",
    "port": 1933,
    "auth_mode": "api_key",
    "root_api_key": "your-secure-secret-key"
  }
}

6.3 启动注意事项

• 开发模式 ：只能绑定 127.0.0.1，不支持网络访问
• 生产模式 ：需要配置 root_api_key，支持外部访问
• 端口占用 ：启动前确保端口未被占用，使用 lsof -ti:1933 检查

---

7. 参考文档

项目文档结构

docs/
├── zh/
│   ├── getting-started/       # 快速入门
│   │   └── 03-quickstart-server.md  # 服务器部署指南
│   ├── api/                   # API 文档
│   │   ├── 01-overview.md     # API 概述
│   │   ├── 02-resources.md    # 资源管理 API
│   │   └── ...
│   ├── concepts/              # 核心概念
│   │   ├── 01-architecture.md # 架构设计
│   │   ├── 04-viking-uri.md   # URI 规范
│   │   └── ...
│   └── guides/                # 使用指南
│       ├── 01-configuration.md # 配置参考
│       ├── 03-deployment.md   # 部署指南
│       └── ...
└── en/                        # 英文版文档
    └── ...

常用文档链接

文档	路径
快速入门	docs/zh/getting-started/
服务器部署	docs/zh/getting-started/03-quickstart-server.md
API 参考	docs/zh/api/
配置指南	docs/zh/guides/01-configuration.md
核心概念	docs/zh/concepts/

---

附录：常用命令

# 查看帮助
openviking-server --help

# 查看版本
openviking-server --version

# 停止服务器（Ctrl+C）
# 或使用以下命令强制停止
lsof -ti:1933 | xargs -r kill -9

# 清理构建文件
make clean

# 完整构建
make build

---

故障排除

常见问题

问题	原因	解决方案
权限错误	.conda 目录属主错误	sudo chown -R $USER:staff ~/.conda/
端口占用	端口已被其他进程使用	`lsof -ti:1933
配置错误	配置文件格式错误	检查 JSON 格式，使用 openviking-server doctor
依赖缺失	Rust/Python 依赖未安装	运行 make check-deps 检查

---

文档版本 : OpenViking v0.3.9
创建日期 : 2026-04-22
适用平台: macOS / Linux