huawei-cloud-openviking-embedding-switch

OpenViking 嵌入模型切换

概述

将 OpenViking 使用的嵌入模型切换为本地 llama-server 或任意兼容 OpenAI 的端点，并正确重建 vectordb 索引，在沙盒安全地重启。

⚠️ 单一用途技能 — 所有操作都通过 job-env-manager REST API（http://127.0.0.1:8090）进行。绝不要在主机上直接运行 openviking-server。

OpenViking 是一个使用向量嵌入进行语义搜索的 AI 上下文数据库。其嵌入模型配置在 ov.conf 的 embedding.dense 部分中。切换到其他嵌入模型时（尤其是向量维度不同时），必须删除并重建现有 vectordb 索引，否则 OpenViking 启动时会引发 EmbeddingRebuildRequiredError。

架构

OpenViking Embedding Model Switch
├── Detect current config     (Read ov.conf embedding.dense section)
├── Validate endpoint         (Check llama-server /v1/embeddings)
├── Modify ov.conf            (Update provider, model, api_base, dimension)
├── Delete vectordb index     (If dimension changed: rm -rf vectordb/context)
├── Restart server            (Kill + exec, NOT stop/start)
└── Verify                    (Health + PID + dimension + log check)

┌─────────────────────────────────────────────────────┐
│                    Host                              │
│                                                      │
│  ┌─────────────┐    REST API   ┌──────────────────┐ │
│  │  Agent       │─────────────▶│  job-env-manager  │ │
│  │  (this skill)│              │  :8090            │ │
│  └─────────────┘              └────────┬─────────┘ │
│                                        │            │
│         ┌──────────────────────────────┼──────┐    │
│         │  bwrap sandbox (openviking)   │      │    │
│         │                               ▼      │    │
│         │  ┌────────────────────────────────┐  │    │
│         │  │  openviking-server :1933       │  │    │
│         │  │  ├── ov.conf (embedding config)│  │    │
│         │  │  ├── vectordb/context/         │  │    │
│         │  │  └── viking/ (metadata)        │  │    │
│         │  └────────────────────────────────┘  │    │
│         └──────────────────────────────────────┘    │
│                                                      │
│         ┌──────────────────────────────────────┐    │
│         │  bwrap sandbox (llama)                │    │
│         │  ┌────────────────────────────────┐  │    │
│         │  │  llama-server :18200           │  │    │
│         │  │  --embeddings --model bge-...  │  │    │
│         │  └────────────────────────────────┘  │    │
│         └──────────────────────────────────────┘    │
│                                                      │
│  Both sandboxes use --share-net, so 127.0.0.1        │
│  endpoints are mutually reachable.                   │
└─────────────────────────────────────────────────────┘

先决条件

先决条件检查：job-env-manager 正在运行

curl -s http://127.0.0.1:8090/api/v1/envs/openviking | python3 -c "import sys,json; print(json.load(sys.stdin)['state'])"

• job-env-manager 正在 http://127.0.0.1:8090 上运行
• OpenViking 环境已部署并正在运行（状态 = running）
• llama-server 正在 127.0.0.1:{port} 上运行，并启用了 --embeddings 标志
• 主机上可用 curl 和 python3
• 无需 AK/SK 或 Huawei Cloud 凭据

IAM 权限策略

此技能通过 job-env-manager REST API 操作本地 bwrap 沙盒，不访问 Huawei Cloud 服务，因此无需 Huawei Cloud IAM 策略。等效访问控制见 references/iam-policies.md。

核心命令 (Core Workflow)

任务 1：检测当前配置

SANDBOX_DIR=$(curl -s http://127.0.0.1:8090/api/v1/envs/openviking \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['cwd'])")

读取沙盒目录中的 ov.conf，获取当前的 embedding.dense 部分（provider、model、dimension）。

任务 2：验证目标嵌入端点

curl -s http://127.0.0.1:${LLAMA_PORT}/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"${MODEL_NAME}","input":"test"}' \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['data'][0]['embedding']))"

如果无法访问，立即停止。如果指定的维度与端点实际输出不符，脚本会自动更正维度。

任务 3：修改 ov.conf

修改前将 ov.conf 备份为 ov.conf.bak。更新 embedding.dense 部分：

字段	描述
provider	嵌入服务提供方名称
model	模型名称（例如，bge-small-zh-v1.5）
api_key	端点的 API 密钥（本地端点留空）
api_base	端点 URL（例如，http://127.0.0.1:18200/v1）
dimension	向量维度（根据端点自动更正）

任务 4：删除不兼容的 vectordb 索引

⚠️ 关键： 如果维度不同，必须执行 rm -rf vectordb/context。否则启动时会引发 EmbeddingRebuildRequiredError。

如果维度未变，则跳过此步骤。

任务 5：在沙盒内重启 openviking-server

⚠️ 注意事项： POST /envs/openviking/stop + start 会重新运行 start.sh，并用 TokenHub 凭据覆盖 ov.conf。不要使用 stop/start。

改为：

1. 从主机终止旧进程：执行 kill $PID，然后轮询端口 1933 是否释放（最长 10 秒）。如果 SIGTERM 未能释放端口，则升级为 kill -9。
2. 清理过期锁文件：.openviking.pid 和 vectordb 的 LOCK 文件。
3. 通过 exec API 启动新服务，并设置 --max-time 15：

curl -s --max-time 15 -X POST http://127.0.0.1:8090/api/v1/envs/openviking/exec \
  -H 'Content-Type: application/json' \
  -d '{"cmd":["bash","-c","nohup /root/runtime/openviking/venv/bin/openviking-server --config /workspace/process_dir/ov.conf > /workspace/process_dir/openviking-server.log 2>&1 & sleep 2 && echo started"]}'

任务 6：验证

1. 带重试循环的运行状况检查（最长 30 秒）：每秒轮询一次 GET /health，直到 healthy=true 或超时
2. PID 变更检查：确认新服务的 PID 与旧 PID 不同（检测端口冲突导致的误报）
3. 集合维度检查：读取 collection_meta.json 并确认 Dimension 与目标值一致
4. 日志错误检查：精确搜索 Traceback|ERROR.*Application startup failed|EmbeddingRebuildRequiredError|DataDirectoryLocked（避免将“Retrying”信息误判为错误）
5. 失败时回滚：如果运行状况检查失败或 PID 未变化，则恢复 ov.conf.bak 并退出并报错

参数确认

参数	必填	描述	示例
MODEL_NAME	是	嵌入模型名称	bge-small-zh-v1.5
LLAMA_PORT	是	llama-server 端口	18200
TARGET_DIMENSION	是	向量维度（错误时会自动修正）	512

# Usage
bash scripts/switch-embedding-model.sh <model_name> <llama_port> <dimension>

常见嵌入模型维度

模型	维度	典型用途
bge-small-zh-v1.5	512	轻量级中文嵌入
bge-large-zh-v1.5	1024	高质量中文嵌入
bge-small-en-v1.5	384	轻量级英文嵌入
bge-base-en-v1.5	768	通用英文嵌入
Qwen3-Embedding-0.6B	1024	Qwen3 嵌入（TokenHub 默认值）

验证

逐步检查和端到端验收标准请参阅 references/verification-method.md。

快速验证：

# 1. Server healthy
curl -s http://127.0.0.1:1933/health \
  | python3 -c "import sys,json; assert json.load(sys.stdin)['healthy']; print('OK')"

# 2. Collection dimension matches target
python3 -c "import json; d=json.load(open('${SANDBOX_DIR}/data/vectordb/context/collection_meta.json')); assert d['Dimension']==${TARGET_DIMENSION}; print('OK')"

# 3. No errors in log (precise pattern)
grep -ci "Traceback\|Application startup failed\|EmbeddingRebuildRequiredError\|DataDirectoryLocked" \
  "${SANDBOX_DIR}/process_dir/openviking-server.log"
# Expected: 0

防护措施

完整规则请参阅 references/guardrails.md。核心原则：

• 始终通过 job-env-manager 运行——切勿直接在主机上执行 openviking-server
• 切勿通过停止/启动来重启——start.sh 会用 TokenHub 凭据覆盖 ov.conf
• 修改前先验证——进行任何配置更改前，目标端点必须能够响应
• 失败时回滚——如果验证失败，则恢复 ov.conf.bak

参考资料

文档	描述
config-reference.md	ov.conf 嵌入部分的字段参考
guardrails.md	安全规则：沙箱执行、重启顺序、回滚
iam-policies.md	等效访问控制（无需 Huawei Cloud IAM）
verification-method.md	各工作流的逐步验证方法
related-commands.md	常用的 job-env-manager 和 curl 命令
acceptance-criteria.md	切换成功的验收标准
troubleshooting.md	常见故障场景的故障排除方法
dataflow-diagram.md	Mermaid 数据流图
demo/example-input.json	切换工作流的示例输入