Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(docs,ci): 完善云上部署文档与 Docker CI 流程 (#320)
Qin Haojie048c201b73ca
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 7f20c045c..ac6bc67f9 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -153,3 +153,51 @@ jobs:VERSION=$(ls dist/*.whl | head -n 1 | xargs basename | cut -d- -f2)echo "Successfully published to PyPI with version: $VERSION"echo "::notice::Successfully published to PyPI with version: $VERSION"++ docker:+ name: Build and Push Docker Image+ needs: [build, permission-check]+ if: >-+ needs.permission-check.outputs.allowed == 'true' &&+ github.event_name == 'release'+ runs-on: ubuntu-latest+ permissions:+ contents: read+ packages: write+ attestations: write+ id-token: write+ steps:+ - name: Checkout repository+ uses: actions/checkout@v6+ with:+ submodules: recursive++ - name: Log in to the Container registry+ uses: docker/login-action@v3+ with:+ registry: ghcr.io+ username: ${{ github.actor }}+ password: ${{ secrets.GITHUB_TOKEN }}++ - name: Extract metadata (tags, labels) for Docker+ id: meta+ uses: docker/metadata-action@v5+ with:+ images: ghcr.io/${{ github.repository }}++ - name: Set up QEMU+ uses: docker/setup-qemu-action@v3++ - name: Set up Docker Buildx+ uses: docker/setup-buildx-action@v3++ - name: Build and push Docker image+ uses: docker/build-push-action@v5+ with:+ context: .+ platforms: linux/amd64,linux/arm64+ push: true+ tags: ${{ steps.meta.outputs.tags }}+ labels: ${{ steps.meta.outputs.labels }}+ build-args: |+ OPENVIKING_VERSION=${{ github.event.release.tag_name }}diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.mdindex c9c9c1d35..fab848bab 100644--- a/docs/en/guides/03-deployment.md+++ b/docs/en/guides/03-deployment.md@@ -197,83 +197,38 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \### Docker-```dockerfile-FROM python:3.11-slim-WORKDIR /app-COPY . .-RUN pip install -e .-EXPOSE 1933-CMD ["python", "-m", "openviking", "serve", "--config", "/etc/openviking/ov.conf"]+OpenViking provides pre-built Docker images published to GitHub Container Registry:++```bash+docker run -d \+ --name openviking \+ -p 1933:1933 \+ -v ~/.openviking/ov.conf:/app/ov.conf \+ -v /var/lib/openviking/data:/app/data \+ --restart unless-stopped \+ ghcr.io/volcengine/openviking:main```+You can also use Docker Compose with the `docker-compose.yml` provided in the project root:+```bash-docker build -t openviking .-docker run -d -p 1933:1933 \- -v /path/to/ov.conf:/etc/openviking/ov.conf:ro \- -v /data/openviking:/data/openviking \- openviking+docker compose up -d```-### Kubernetes--```yaml-apiVersion: apps/v1-kind: Deployment-metadata:- name: openviking-spec:- replicas: 1- selector:- matchLabels:- app: openviking- template:- metadata:- labels:- app: openviking- spec:- containers:- - name: openviking- image: openviking:latest- ports:- - containerPort: 1933- volumeMounts:- - name: config- mountPath: /etc/openviking- readOnly: true- - name: data- mountPath: /data/openviking- livenessProbe:- httpGet:- path: /health- port: 1933- initialDelaySeconds: 5- periodSeconds: 10- readinessProbe:- httpGet:- path: /ready- port: 1933- initialDelaySeconds: 10- periodSeconds: 15- volumes:- - name: config- configMap:- name: openviking-config- - name: data- persistentVolumeClaim:- claimName: openviking-data-----apiVersion: v1-kind: Service-metadata:- name: openviking-spec:- selector:- app: openviking- ports:- - port: 1933- targetPort: 1933+To build the image yourself: `docker build -t openviking:latest .`++### Kubernetes + Helm++The project provides a Helm chart located at `examples/k8s-helm/`:++```bash+helm install openviking ./examples/k8s-helm \+ --set openviking.config.embedding.dense.api_key="YOUR_API_KEY" \+ --set openviking.config.vlm.api_key="YOUR_API_KEY"```+For a detailed cloud deployment guide (including Volcengine TOS + VikingDB + Ark configuration), see the [Cloud Deployment Guide](../../../examples/cloud/GUIDE.md).+## Health Checks| Endpoint | Auth | Purpose |diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.mdindex eca1d98e0..e20ba6671 100644--- a/docs/zh/guides/03-deployment.md+++ b/docs/zh/guides/03-deployment.md@@ -191,83 +191,38 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \### Docker-```dockerfile-FROM python:3.11-slim-WORKDIR /app-COPY . .-RUN pip install -e .-EXPOSE 1933-CMD ["python", "-m", "openviking", "serve", "--config", "/etc/openviking/ov.conf"]+OpenViking 提供预构建的 Docker 镜像,发布在 GitHub Container Registry:++```bash+docker run -d \+ --name openviking \+ -p 1933:1933 \+ -v ~/.openviking/ov.conf:/app/ov.conf \+ -v /var/lib/openviking/data:/app/data \+ --restart unless-stopped \+ ghcr.io/volcengine/openviking:main```+也可以使用 Docker Compose,项目根目录提供了 `docker-compose.yml`:+```bash-docker build -t openviking .-docker run -d -p 1933:1933 \- -v /path/to/ov.conf:/etc/openviking/ov.conf:ro \- -v /data/openviking:/data/openviking \- openviking+docker compose up -d```-### Kubernetes--```yaml-apiVersion: apps/v1-kind: Deployment-metadata:- name: openviking-spec:- replicas: 1- selector:- matchLabels:- app: openviking- template:- metadata:- labels:- app: openviking- spec:- containers:- - name: openviking- image: openviking:latest- ports:- - containerPort: 1933- volumeMounts:- - name: config- mountPath: /etc/openviking- readOnly: true- - name: data- mountPath: /data/openviking- livenessProbe:- httpGet:- path: /health- port: 1933- initialDelaySeconds: 5- periodSeconds: 10- readinessProbe:- httpGet:- path: /ready- port: 1933- initialDelaySeconds: 10- periodSeconds: 15- volumes:- - name: config- configMap:- name: openviking-config- - name: data- persistentVolumeClaim:- claimName: openviking-data-----apiVersion: v1-kind: Service-metadata:- name: openviking-spec:- selector:- app: openviking- ports:- - port: 1933- targetPort: 1933+如需自行构建镜像:`docker build -t openviking:latest .`++### Kubernetes + Helm++项目提供了 Helm chart,位于 `examples/k8s-helm/`:++```bash+helm install openviking ./examples/k8s-helm \+ --set openviking.config.embedding.dense.api_key="YOUR_API_KEY" \+ --set openviking.config.vlm.api_key="YOUR_API_KEY"```+详细的云上部署指南(包括火山引擎 TOS + VikingDB + 方舟配置)请参考 [云上部署指南](../../../examples/cloud/GUIDE.md)。+## 健康检查| 端点 | 认证 | 用途 |diff --git a/examples/cloud/GUIDE.md b/examples/cloud/GUIDE.mdindex a7dd002b7..d4da87b55 100644--- a/examples/cloud/GUIDE.md+++ b/examples/cloud/GUIDE.md@@ -1,7 +1,27 @@-# OpenViking 上云部署指南+# OpenViking 云上部署指南(火山引擎)本文档介绍如何将 OpenViking 部署到火山引擎云上,使用 TOS(对象存储)+ VikingDB(向量数据库)+ 方舟大模型作为后端。+## 概览++云上部署架构:++```+用户请求 → OpenViking Server (1933)+ ├── AGFS → TOS (S3 兼容协议,存储文件数据)+ ├── VectorDB → VikingDB (向量检索)+ ├── Embedding → 方舟 API (doubao-embedding-vision)+ └── VLM → 方舟 API (doubao-seed)+```++> **地域说明**:TOS 和 VikingDB 均需要选择地域(region),不同地域对应不同的服务域名。所有云服务应部署在同一地域以降低网络延迟。目前支持的地域包括 `cn-beijing`、`cn-shanghai`、`cn-guangzhou` 等,本文以 `cn-beijing` 为例。++## 前置条件++- 火山引擎账号([注册地址](https://console.volcengine.com/))+- 已安装 OpenViking(`pip install openviking` 或从源码安装)+- Python 3.11++---## 1. 开通云服务@@ -14,19 +34,27 @@ TOS 用于持久化存储 OpenViking 的文件数据(AGFS 后端)。2. 进入 **对象存储 TOS** → 开通服务3. 创建存储桶:- 桶名称:如 `openvikingdata`- - 地域:`cn-beijing`(需与其他服务保持一致)+ - 地域:如 `cn-beijing`(需与 VikingDB 等其他服务保持一致)- 存储类型:标准存储- 访问权限:私有-4. 记录桶名称和地域,填入配置文件的 `storage.agfs.s3` 部分+4. 记录桶名称、地域和 S3 兼容 endpoint,填入配置文件的 `storage.agfs.s3` 部分++> **注意**:AGFS 使用 S3 兼容协议访问 TOS,endpoint 需要使用 S3 兼容域名(带 `tos-s3-` 前缀),而非 TOS 控制台显示的标准域名。不同地域的 endpoint 不同,请查阅 [TOS 地域和访问域名文档](https://www.volcengine.com/docs/6349/107356) 获取你所在地域的 S3 兼容 endpoint。例如:+>+> | 地域 | S3 兼容 endpoint |+> |------|-----------------|+> | cn-beijing | `https://tos-s3-cn-beijing.volces.com` |+> | cn-shanghai | `https://tos-s3-cn-shanghai.volces.com` |+> | cn-guangzhou | `https://tos-s3-cn-guangzhou.volces.com` |### 1.2 开通 VikingDB(向量数据库)VikingDB 用于存储和检索向量嵌入。-1. 进入 [火山引擎控制台](https://console.volcengine.com/) → **智能数据** → **向量数据库 VikingDB**-2. 开通服务(按量付费即可)-3. VikingDB 的 API Host 默认为:`api-vikingdb.vikingdb.cn-beijing.volces.com`-4. 无需手动创建 Collection,OpenViking 启动后会自动创建+1. 登陆 [火山引擎控制台](https://console.volcengine.com/) → [进入 VikingDB 下单开通界面](https://console.volcengine.com/vikingdb/region:vikingdb+cn-beijing/home) -> 选择对应的地域并开通向量数据库+2. 开通服务(按量付费即可),选择与 TOS 相同的地域+3. 无需手动创建 Collection,OpenViking 启动后会自动创建+4. 在配置文件中填写 `storage.vectordb.volcengine.region`,OpenViking 会自动路由到对应地域的 VikingDB 服务### 1.3 申请 AK/SK(IAM 访问密钥)@@ -43,7 +71,6 @@ AK/SK 同时用于 TOS 和 VikingDB 的鉴权。5. 将 AK/SK 填入配置文件中的以下位置:- `storage.vectordb.volcengine.ak` / `sk`- `storage.agfs.s3.access_key` / `secret_key`- - `rerank.ak` / `sk`(如果使用 rerank)### 1.4 申请方舟 API Key@@ -55,94 +82,340 @@ AK/SK 同时用于 TOS 和 VikingDB 的鉴权。4. 确认以下模型已开通(在 **模型广场** 中申请):- `doubao-embedding-vision-250615`(多模态 Embedding)- `doubao-seed-1-8-251228`(VLM 推理)- - `doubao-seed-rerank`(Rerank,可选)5. 将 API Key 填入配置文件的 `embedding.dense.api_key` 和 `vlm.api_key`----## 2. 编写配置文件+## 2. 准备配置文件-参考本目录下的 [ov.conf](./ov.conf),将上述步骤获取的凭据填入。+### 2.1 复制示例配置-关键字段说明:+```bash+cp examples/cloud/ov.conf.example examples/cloud/ov.conf+```++### 2.2 编辑配置++打开 `examples/cloud/ov.conf`,将占位符替换为真实值。需要替换的字段如下:++| 占位符 | 替换为 | 说明 |+|--------|--------|------|+| `<your-root-api-key>` | 自定义强密码 | 管理员密钥,用于多租户管理 |+| `<your-volcengine-ak>` | IAM Access Key ID | 火山引擎 AK,用于 TOS / VikingDB |+| `<your-volcengine-sk>` | IAM Secret Access Key | 火山引擎 SK |+| `<your-tos-bucket>` | TOS 桶名称 | 如 `openvikingdata` |+| `<your-ark-api-key>` | 方舟 API Key | 用于 Embedding 和 VLM |++此外,还需根据实际地域修改以下字段(示例中默认为 `cn-beijing`):| 字段 | 说明 ||------|------|-| `server.root_api_key` | 管理员密钥,用于多租户管理,设置一个强密码 |-| `storage.vectordb.backend` | 设置为 `volcengine` 使用云端 VikingDB |-| `storage.vectordb.volcengine.ak/sk` | IAM 的 AK/SK |-| `storage.agfs.backend` | 设置为 `s3` 使用 TOS 存储 |-| `storage.agfs.s3.bucket` | TOS 桶名称 |-| `storage.agfs.s3.endpoint` | TOS 端点,北京为 `https://tos-cn-beijing.volces.com` |-| `storage.agfs.s3.access_key/secret_key` | IAM 的 AK/SK |-| `embedding.dense.api_key` | 方舟 API Key |-| `vlm.api_key` | 方舟 API Key |+| `storage.vectordb.volcengine.region` | VikingDB 地域,如 `cn-beijing`、`cn-shanghai`、`cn-guangzhou` |+| `storage.agfs.s3.region` | TOS 地域,需与桶所在地域一致 |+| `storage.agfs.s3.endpoint` | TOS 的 S3 兼容 endpoint,需与地域匹配(参考第 1.1 节) |++替换后的配置示例(脱敏):++```json+{+ "server": {+ "root_api_key": "my-strong-secret-key-2024"+ },+ "storage": {+ "vectordb": {+ "volcengine": {+ "region": "cn-beijing",+ "ak": "AKLTxxxxxxxxxxxx",+ "sk": "T1dYxxxxxxxxxxxx"+ }+ },+ "agfs": {+ "s3": {+ "bucket": "openvikingdata",+ "region": "cn-beijing",+ "access_key": "AKLTxxxxxxxxxxxx",+ "secret_key": "T1dYxxxxxxxxxxxx",+ "endpoint": "https://tos-s3-cn-beijing.volces.com"+ }+ }+ },+ "embedding": {+ "dense": {+ "api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"+ }+ },+ "vlm": {+ "api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"+ }+}+```++> **注意**:`ov.conf` 已被 `.gitignore` 排除,不会被提交到版本库。请妥善保管你的凭据。---## 3. 启动服务-### 方式一:Docker(推荐)+| 方式 | 需要容器运行时 | 适合节点数 | 环境隔离 | 弹性伸缩 | 典型场景 |+|------|:---:|:---:|:---:|:---:|------|+| **Docker(推荐)** | 是 | 单机 | 容器隔离 | 不支持 | 开发、测试、单机生产,最省事 |+| systemd | 否 | 单机 | 无 | 不支持 | VM 上不想装 Docker |+| Kubernetes + Helm | 是 | 暂不支持多节点 | 容器 + 编排 | 支持 | 已有 K8s 集群的团队 |++> **开发调试**:如果只是本地快速验证,可以直接运行:+> ```bash+> pip install openviking+>+> # 方式 A:放到默认路径+> mkdir -p ~/.openviking && cp examples/cloud/ov.conf ~/.openviking/ov.conf+> openviking-server+>+> # 方式 B:通过环境变量指定+> OPENVIKING_CONFIG_FILE=examples/cloud/ov.conf openviking-server+> ```++### 方式一:systemd++适合在 VM 上以系统服务方式长期运行。++1. 安装 OpenViking:++```bash+pip install openviking+```++2. 将配置文件放到固定路径:++```bash+sudo mkdir -p /etc/openviking+sudo cp ~/.openviking/ov.conf /etc/openviking/ov.conf+sudo chmod 600 /etc/openviking/ov.conf+```++3. 创建 systemd service 文件:++```bash+sudo tee /etc/systemd/system/openviking.service > /dev/null << 'EOF'+[Unit]+Description=OpenViking Server+After=network.target++[Service]+Type=simple+Environment=OPENVIKING_CONFIG_FILE=/etc/openviking/ov.conf+ExecStart=/usr/local/bin/openviking-server # 替换为 which openviking-server 的实际输出+Restart=on-failure+RestartSec=5s+StandardOutput=journal+StandardError=journal+NoNewPrivileges=true+PrivateTmp=true++[Install]+WantedBy=multi-user.target+EOF+```++4. 启动服务:++```bash+sudo systemctl daemon-reload+sudo systemctl start openviking+sudo systemctl status openviking+```++5. 确认服务正常后,设置开机自启(可选):```bash-# 构建镜像(如果不使用预构建镜像)-docker build -t openviking:latest .+sudo systemctl enable openviking+```++常用管理命令:++```bash+sudo systemctl stop openviking # 停止服务+sudo systemctl restart openviking # 重启服务+journalctl -u openviking -f # 查看实时日志+```++### 方式二:Docker++单容器场景用 `docker run` 或 `docker compose` 均可,效果相同。++**docker run:**++```bash+# 假设你的配置文件在 ~/.openviking/ov.conf+#+# -p 端口映射,宿主机端口:容器端口,启动后通过 localhost:1933 访问+# -v 挂载宿主机文件到容器内,格式为 宿主机路径:容器内路径+# ov.conf 挂载是必填的,data 目录用于持久化数据(容器删除后不丢失)+# --restart 进程崩溃或机器重启后自动拉起-# 启动docker run -d \--name openviking \-p 1933:1933 \- -v $(pwd)/examples/cloud/ov.conf:/app/ov.conf \+ -v ~/.openviking/ov.conf:/app/ov.conf \-v /var/lib/openviking/data:/app/data \--restart unless-stopped \- openviking:latest+ ghcr.io/volcengine/openviking:main+```++> 将 `~/.openviking/ov.conf` 替换为你实际的配置文件路径。++常用管理命令:++```bash+docker logs openviking # 查看日志+docker logs -f openviking # 实时跟踪日志+docker stop openviking # 停止服务+docker restart openviking # 重启服务+docker rm -f openviking # 删除容器(重新 docker run 前需要先删除)+```++**docker compose:**++项目根目录的 `docker-compose.yml` 默认从 `/var/lib/openviking/ov.conf` 读取配置:++```bash+# 把你的配置文件复制到 docker-compose.yml 期望的路径+sudo mkdir -p /var/lib/openviking+sudo cp ~/.openviking/ov.conf /var/lib/openviking/ov.conf++# 在项目根目录下启动(-d 表示后台运行)+docker compose up -d```-### 方式二:Docker Compose+> 如果配置文件不在 `/var/lib/openviking/ov.conf`,需要修改 `docker-compose.yml` 中 `volumes` 的挂载路径。-修改 `docker-compose.yml` 中的配置挂载路径后:+常用管理命令:```bash-docker-compose up -d+docker compose stop # 停止服务+docker compose restart # 重启服务+docker compose logs -f # 查看实时日志```+> 如需自行构建镜像:`docker build -t openviking:latest .`+### 方式三:Kubernetes + Helm+Helm chart 默认的 `values.yaml` 只包含 embedding 和 vlm 配置。云上部署需要补充 storage、server 等字段。++推荐创建自定义 values 文件 `my-values.yaml`:++```yaml+openviking:+ config:+ server:+ root_api_key: "my-strong-secret-key-2024"+ storage:+ workspace: /app/data+ vectordb:+ name: context+ backend: volcengine+ project: default+ volcengine:+ region: cn-beijing+ ak: "AKLTxxxxxxxxxxxx"+ sk: "T1dYxxxxxxxxxxxx"+ agfs:+ port: 1833+ log_level: warn+ backend: s3+ timeout: 10+ retry_times: 3+ s3:+ bucket: "openvikingdata"+ region: cn-beijing+ access_key: "AKLTxxxxxxxxxxxx"+ secret_key: "T1dYxxxxxxxxxxxx"+ endpoint: "https://tos-s3-cn-beijing.volces.com"+ prefix: openviking+ use_ssl: true+ use_path_style: false+ embedding:+ dense:+ model: "doubao-embedding-vision-250615"+ api_key: "your-ark-api-key"+ api_base: "https://ark.cn-beijing.volces.com/api/v3"+ dimension: 1024+ provider: volcengine+ input: multimodal+ vlm:+ model: "doubao-seed-1-8-251228"+ api_key: "your-ark-api-key"+ api_base: "https://ark.cn-beijing.volces.com/api/v3"+ temperature: 0.0+ max_retries: 3+ provider: volcengine+ thinking: false+ auto_generate_l0: true+ auto_generate_l1: true+ default_search_mode: thinking+ default_search_limit: 3+ enable_memory_decay: true+ memory_decay_check_interval: 3600+```++然后安装:++```bash+helm install openviking ./examples/k8s-helm -f my-values.yaml+```++或者通过 `--set` 逐个传参(适合 CI/CD):+```bashhelm install openviking ./examples/k8s-helm \+ --set openviking.config.server.root_api_key="my-strong-secret-key-2024" \--set openviking.config.embedding.dense.api_key="YOUR_ARK_API_KEY" \--set openviking.config.vlm.api_key="YOUR_ARK_API_KEY" \+ --set openviking.config.storage.vectordb.backend="volcengine" \--set openviking.config.storage.vectordb.volcengine.ak="YOUR_AK" \- --set openviking.config.storage.vectordb.volcengine.sk="YOUR_SK"+ --set openviking.config.storage.vectordb.volcengine.sk="YOUR_SK" \+ --set openviking.config.storage.agfs.backend="s3" \+ --set openviking.config.storage.agfs.s3.bucket="openvikingdata" \+ --set openviking.config.storage.agfs.s3.access_key="YOUR_AK" \+ --set openviking.config.storage.agfs.s3.secret_key="YOUR_SK" \+ --set openviking.config.storage.agfs.s3.endpoint="https://tos-s3-cn-beijing.volces.com"```-### 方式四:直接运行+----```bash-pip install openviking-export OPENVIKING_CONFIG_FILE=$(pwd)/examples/cloud/ov.conf-openviking-server-```+## 4. 验证-### 验证启动+### 4.1 健康检查```bash-# 健康检查curl http://localhost:1933/health# 期望返回: {"status":"ok"}+```++### 4.2 就绪检查-# 就绪检查(验证 AGFS、VikingDB 连接)+就绪接口会检测 AGFS(TOS)和 VikingDB 的连接状态,是验证凭据是否正确的关键步骤:++```bashcurl http://localhost:1933/ready# 期望返回: {"status":"ready","checks":{"agfs":"ok","vectordb":"ok","api_key_manager":"ok"}}```+如果某个组件报错,请检查:++| checks 字段 | 失败原因 | 排查方向 |+|-------------|---------|---------|+| `agfs` | TOS 连接失败 | 检查 bucket、endpoint、AK/SK 是否正确 |+| `vectordb` | VikingDB 连接失败 | 检查 region、AK/SK、服务是否已开通 |+| `api_key_manager` | root_api_key 未配置 | 检查 `server.root_api_key` 字段 |+----## 4. 注册租户和用户+## 5. 多租户管理OpenViking 支持多租户隔离。配置了 `root_api_key` 后自动启用多租户模式。-### 4.1 创建租户(Account)+### 5.1 创建租户(Account)使用 `root_api_key` 创建租户,同时会生成一个管理员用户:@@ -169,7 +442,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \}```-### 4.2 注册普通用户+### 5.2 注册普通用户租户管理员可以为租户添加用户:@@ -195,7 +468,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts/my-team/users \}```-### 4.3 查看租户下的用户+### 5.3 查看租户下的用户```bashcurl http://localhost:1933/api/v1/admin/accounts/my-team/users \@@ -204,142 +477,65 @@ curl http://localhost:1933/api/v1/admin/accounts/my-team/users \----## 5. 使用+## 6. 运行示例-以下操作使用用户的 API Key 进行。+`examples/cloud/` 目录下提供了完整的多租户 demo 脚本,演示从用户创建到数据使用的全流程。-### 5.1 添加资源+### 6.1 setup_users.py — 初始化租户和用户-```bash-# 添加一个 URL 资源-curl -X POST http://localhost:1933/api/v1/resources \- -H "X-API-Key: USER_API_KEY" \- -H "Content-Type: application/json" \- -d '{- "path": "https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md",- "reason": "项目文档"- }'+创建租户 `demo-team`,注册 alice(管理员)和 bob(普通用户),并将 API Key 写入 `user_keys.json` 供后续脚本使用。-# 上传本地文件(先上传到临时路径,再添加为资源)-curl -X POST http://localhost:1933/api/v1/resources/temp_upload \- -H "X-API-Key: USER_API_KEY" \- -F "file=@./my-document.pdf"--# 然后使用返回的 temp_path 添加资源-curl -X POST http://localhost:1933/api/v1/resources \- -H "X-API-Key: USER_API_KEY" \- -H "Content-Type: application/json" \- -d '{- "temp_path": "/tmp/upload_xyz",- "reason": "内部文档"- }'+```bash+# 确保 server 已启动,且 root_api_key 与 ov.conf 一致+uv run examples/cloud/setup_users.py --url http://localhost:1933 --root-key <your-root-api-key>```-### 5.2 等待处理完成+### 6.2 alice.py — 技术负责人的使用流程-添加资源后,系统会异步进行解析和向量化。等待处理完成:+Alice 演示:添加项目文档 → 语义搜索 → 多轮对话 → 沉淀记忆 → 回顾记忆。```bash-curl -X POST http://localhost:1933/api/v1/system/wait \- -H "X-API-Key: USER_API_KEY" \- -H "Content-Type: application/json" \- -d '{"timeout": 120}'+uv run examples/cloud/alice.py```-### 5.3 语义搜索+脚本会自动从 `user_keys.json` 读取 API Key。也可以手动指定:```bash-curl -X POST http://localhost:1933/api/v1/search/find \- -H "X-API-Key: USER_API_KEY" \- -H "Content-Type: application/json" \- -d '{- "query": "OpenViking 是什么",- "limit": 5- }'+uv run examples/cloud/alice.py --url http://localhost:1933 --api-key <alice_key>```-### 5.4 浏览文件系统+### 6.3 bob.py — 新入职成员的使用流程-```bash-# 列出根目录-curl "http://localhost:1933/api/v1/fs/ls?uri=viking://" \- -H "X-API-Key: USER_API_KEY"+Bob 演示:浏览团队资源 → 回顾团队记忆(Alice 沉淀的决策) → 添加自己的资源 → 对话 → 沉淀记忆 → 带上下文搜索。-# 查看目录树-curl "http://localhost:1933/api/v1/fs/tree?uri=viking://&depth=2" \- -H "X-API-Key: USER_API_KEY"-```--### 5.5 读取内容+建议在 alice.py 执行完毕后运行,这样 Bob 可以看到 Alice 沉淀的团队记忆:```bash-# 读取文件内容-curl "http://localhost:1933/api/v1/content/read?uri=viking://resources/doc1" \- -H "X-API-Key: USER_API_KEY"--# 读取摘要-curl "http://localhost:1933/api/v1/content/abstract?uri=viking://resources/doc1" \- -H "X-API-Key: USER_API_KEY"+uv run examples/cloud/bob.py```-### 5.6 会话管理(Memory)+### 完整流程汇总```bash-# 创建会话-curl -X POST http://localhost:1933/api/v1/sessions \- -H "X-API-Key: USER_API_KEY"--# 添加对话消息-curl -X POST http://localhost:1933/api/v1/sessions/{session_id}/messages \- -H "X-API-Key: USER_API_KEY" \- -H "Content-Type: application/json" \- -d '{- "role": "user",- "content": "帮我分析这个文档的核心观点"- }'--# 带会话上下文的搜索-curl -X POST http://localhost:1933/api/v1/search/search \- -H "X-API-Key: USER_API_KEY" \- -H "Content-Type: application/json" \- -d '{- "query": "核心观点",- "session_id": "SESSION_ID",- "limit": 5- }'-```--### 5.7 Python SDK 使用--```python-import openviking as ov+# 1. 启动服务(确保 ~/.openviking/ov.conf 已就位)+openviking-server &-client = ov.SyncHTTPClient(- url="http://localhost:1933",- api_key="USER_API_KEY",- agent_id="my-agent",- timeout=120.0, # HTTP request timeout in seconds (default: 60.0)-)-client.initialize()+# 2. 等待服务就绪+curl http://localhost:1933/ready-# 添加资源-client.add_resource(- path="https://example.com/doc.pdf",- reason="参考文档"-)-client.wait_processed(timeout=120)+# 3. 创建用户+uv run examples/cloud/setup_users.py --root-key <your-root-api-key>-# 搜索-results = client.find("OpenViking 架构设计", limit=5)-for r in results:- print(r.uri, r.score)+# 4. Alice: 添加文档 + 对话 + 沉淀记忆+uv run examples/cloud/alice.py-client.close()+# 5. Bob: 浏览团队资源和记忆 + 入职学习+uv run examples/cloud/bob.py```----## 6. 运维+## 7. 运维### 日志@@ -349,6 +545,8 @@ client.close()docker logs -f openviking```+配置文件中 `log.level` 可调整日志级别(`DEBUG` / `INFO` / `WARN` / `ERROR`)。+### 监控- 健康检查:`GET /health`@@ -359,3 +557,113 @@ docker logs -f openviking- **TOS 数据**:通过 TOS 控制台配置跨区域复制或定期备份- **本地数据**(如使用 PVC):定期快照 PersistentVolume++---++## 8. 常见问题++### systemd 启动失败(status=203/EXEC)++`status=203/EXEC` 表示 systemd 找不到 `ExecStart` 指定的可执行文件。常见于使用 venv / conda 环境安装 OpenViking 的情况,`openviking-server` 不在 `/usr/local/bin/` 下。++排查步骤:++```bash+# 1. 查找实际路径+which openviking-server++# 2. 将输出路径替换到 service 文件的 ExecStart+sudo sed -i 's|ExecStart=.*|ExecStart=/实际/路径/openviking-server|' /etc/systemd/system/openviking.service++# 3. 重新加载并启动+sudo systemctl daemon-reload+sudo systemctl restart openviking+sudo systemctl status openviking+```++### docker: command not found++系统未安装 Docker,请参考 [Docker 官方安装文档](https://docs.docker.com/engine/install/) 选择对应系统的安装方式。安装完成后启动 Docker:++```bash+sudo systemctl start docker+```++然后重新运行 `docker run` 命令即可。++### TOS 连接失败(agfs check failed)++- **endpoint 错误**:确认使用 S3 兼容 endpoint(带 `tos-s3-` 前缀),不要用标准 endpoint(`tos-cn-` 前缀)+- **地域不匹配**:确认 `storage.agfs.s3.region` 和 `storage.agfs.s3.endpoint` 与桶所在地域一致+- **bucket 不存在**:确认 TOS 控制台中桶已创建,且名称和地域与配置一致+- **AK/SK 无权限**:确认 IAM 子用户拥有 `TOSFullAccess` 或对应桶的访问策略++### VikingDB 鉴权失败(vectordb check failed)++- **服务未开通**:在火山引擎控制台确认 VikingDB 已开通+- **地域错误**:确认 `storage.vectordb.volcengine.region` 与开通服务的地域一致+- **AK/SK 错误**:确认 `storage.vectordb.volcengine.ak/sk` 与 IAM 密钥一致+- **权限不足**:确认 IAM 子用户拥有 `VikingDBFullAccess` 策略++### Embedding 模型调用失败++- **模型未开通**:在方舟控制台 **模型广场** 中确认 `doubao-embedding-vision-250615` 已申请并通过+- **API Key 错误**:确认 `embedding.dense.api_key` 填写正确+- **API Base 错误**:确认为 `https://ark.cn-beijing.volces.com/api/v3`++### helm: command not found++系统未安装 Helm,需要先安装:++```bash+curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash+```++安装后验证:++```bash+helm version+```++### Kubernetes cluster unreachable++```+Error: INSTALLATION FAILED: Kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp [::1]:8080: connect: connection refused+```++服务器上没有运行 Kubernetes 集群。可以使用 k3s 快速搭建轻量级集群:++```bash+# 安装 k3s+curl -sfL https://get.k3s.io | sh -++# 配置 kubeconfig+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml++# 永久生效+echo 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> ~/.bashrc++# 验证集群就绪+kubectl get nodes+```++看到节点状态为 `Ready` 后,再执行 `helm install` 命令。++### helm install 时 path not found++```+Error: INSTALLATION FAILED: path "./examples/k8s-helm" not found+```++需要在 OpenViking 项目根目录下执行 `helm install` 命令:++```bash+cd /path/to/OpenViking+helm install openviking ./examples/k8s-helm -f my-values.yaml+```++### Helm 安装后 Pod CrashLoopBackOff++- 检查 `kubectl logs <pod-name>`,通常是配置字段缺失+- 确认 values 文件中包含完整的 storage、embedding、vlm 配置(参考第 3 节 Helm 部分)+- 确认 `openviking.config` 下的 JSON 结构正确(Helm 会将其序列化为 ov.conf)diff --git a/examples/cloud/ov.conf.example b/examples/cloud/ov.conf.exampleindex c57f13b53..a8440c1bd 100644--- a/examples/cloud/ov.conf.example+++ b/examples/cloud/ov.conf.example@@ -2,7 +2,7 @@"server": {"host": "0.0.0.0","port": 1933,- "root_api_key": "${ROOT_API_KEY}",+ "root_api_key": "<your-root-api-key>","cors_origins": ["*"]},"storage": {@@ -13,8 +13,8 @@"project": "default","volcengine": {"region": "cn-beijing",- "ak": "${VOLCENGINE_AK}",- "sk": "${VOLCENGINE_SK}"+ "ak": "<your-volcengine-ak>",+ "sk": "<your-volcengine-sk>"}},"agfs": {@@ -24,10 +24,10 @@"timeout": 10,"retry_times": 3,"s3": {- "bucket": "${TOS_BUCKET}",+ "bucket": "<your-tos-bucket>","region": "cn-beijing",- "access_key": "${VOLCENGINE_AK}",- "secret_key": "${VOLCENGINE_SK}",+ "access_key": "<your-volcengine-ak>",+ "secret_key": "<your-volcengine-sk>","endpoint": "https://tos-s3-cn-beijing.volces.com","prefix": "openviking","use_ssl": true,@@ -38,7 +38,7 @@"embedding": {"dense": {"model": "doubao-embedding-vision-250615",- "api_key": "${ARK_API_KEY}",+ "api_key": "<your-ark-api-key>","api_base": "https://ark.cn-beijing.volces.com/api/v3","dimension": 1024,"provider": "volcengine",@@ -47,21 +47,13 @@},"vlm": {"model": "doubao-seed-1-8-251228",- "api_key": "${ARK_API_KEY}",+ "api_key": "<your-ark-api-key>","api_base": "https://ark.cn-beijing.volces.com/api/v3","temperature": 0.0,"max_retries": 3,"provider": "volcengine","thinking": false},- "rerank": {- "ak": "${VOLCENGINE_AK}",- "sk": "${VOLCENGINE_SK}",- "host": "api-vikingdb.vikingdb.cn-beijing.volces.com",- "model_name": "doubao-seed-rerank",- "model_version": "251028",- "threshold": 0.1- },"auto_generate_l0": true,"auto_generate_l1": true,"default_search_mode": "thinking",