Skip to content

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

Update 03-quickstart-server.md (#174)

Yaoyaodbaba28e3b6d
diff --git a/docs/zh/getting-started/03-quickstart-server.md b/docs/zh/getting-started/03-quickstart-server.md
index 6dba7cbdf..1496532e8 100644
--- a/docs/zh/getting-started/03-quickstart-server.md
+++ b/docs/zh/getting-started/03-quickstart-server.md
@@ -85,15 +85,25 @@ finally:
```json
{
- "url": "http://localhost:1933"
+ "url": "http://localhost:1933",
+ "api_key": "your-key"
}
```
然后直接使用 CLI 命令:
```bash
-python -m openviking health
-python -m openviking find "what is openviking"
+# 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"
```
如果配置文件在其他位置,通过环境变量指定:
@@ -119,6 +129,191 @@ curl -X POST http://localhost:1933/api/v1/search/find \
-d '{"query": "what is openviking"}'
```
+## 推荐云端部署方案:火山引擎 ECS
+
+为了获得高性能、可扩展的 Context Memory 能力,能够像“长期记忆”一样为 Agent 提供支持,我们推荐使用 **火山引擎云服务器 (ECS)** 结合 **veLinux** 操作系统进行部署。
+
+### 1. 实例采购配置
+
+在[火山引擎 ECS 控制台](https://console.volcengine.com/ecs/region:ecs+cn-beijing/dashboard?)创建实例时,推荐以下配置:
+
+| 配置项 | 推荐参数 | 说明 |
+| :--- | :--- | :--- |
+| **镜像** | **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-250615)
+ "input" : "multimodal" // if use doubao-embedding-vision-250615, 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-1-8-251228 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"
+```
+
+
## 下一步
- [服务部署](../guides/03-deployment.md) - 配置、认证和部署选项