huawei-cloud-openviking-embedding-switch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenViking Embedding Model Switch

OpenViking嵌入模型切换

概述

Switch the embedding model used by OpenViking to a local llama-server or any OpenAI-compatible endpoint, with proper vectordb index rebuild and sandbox-safe restart.

⚠️ Single-purpose skill — all operations go through the job-env-manager REST API (
http://127.0.0.1:8090
). Never run
openviking-server
directly on the host.

OpenViking is an AI context database that uses vector embeddings for semantic search. Its embedding model is configured in

ov.conf

under the

embedding.dense

section. When switching to a different embedding model (especially one with a different vector dimension), the existing vectordb index must be deleted and rebuilt — otherwise OpenViking raises

EmbeddingRebuildRequiredError

on startup.

将OpenViking使用的嵌入模型切换到本地llama-server或任何兼容OpenAI的端点，同时完成正确的向量数据库索引重建和沙箱安全重启。

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

OpenViking是一款AI上下文数据库，使用向量嵌入实现语义搜索。其嵌入模型配置在

ov.conf

的

embedding.dense

部分。当切换到不同的嵌入模型（尤其是向量维度不同的模型）时，必须删除并重建现有的向量数据库索引——否则OpenViking在启动时会抛出

EmbeddingRebuildRequiredError

。

Architecture

架构

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.                   │
└─────────────────────────────────────────────────────┘

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.                   │
└─────────────────────────────────────────────────────┘

Prerequisites

前置条件

Prerequisite check: job-env-manager running

bash

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 running on
```
http://127.0.0.1:8090
```
OpenViking environment deployed and running (state =
```
running
```
)
llama-server running at
```
127.0.0.1:{port}
```
with
```
--embeddings
```
flag
curl and python3 available on the host
No AK/SK or Huawei Cloud credentials required

前置条件检查：job-env-manager正在运行

bash

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或华为云凭证

IAM Permission Policies

IAM权限策略

This skill operates on local bwrap sandboxes via the job-env-manager REST API and does not access Huawei Cloud services — no Huawei Cloud IAM policies required. Equivalent access controls are listed in references/iam-policies.md.

本技能通过job-env-manager REST API操作本地bwrap沙箱，不访问华为云服务——无需华为云IAM策略。等效访问控制规则详见references/iam-policies.md。

核心命令 (Core Workflow)

核心工作流

Task 1: Detect Current Configuration

任务1：检测当前配置

bash

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'])")

Read

ov.conf

under the sandbox directory to get the current

embedding.dense

section (provider, model, dimension).

bash

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）。

Task 2: Validate Target Embedding Endpoint

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

bash

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']))"

If unreachable, STOP. The script auto-corrects the dimension if the specified value doesn't match the actual endpoint output.

bash

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']))"

如果端点不可达，终止操作。如果指定的维度值与端点实际输出不匹配，脚本会自动修正维度。

Task 3: Modify ov.conf

任务3：修改ov.conf

Backs up

ov.conf

ov.conf.bak

before modifying. Updates the

embedding.dense

section:

Field	Description
`provider`	Embedding provider name
`model`	Model name (e.g., `bge-small-zh-v1.5` )
`api_key`	API key for the endpoint (empty for local)
`api_base`	Endpoint URL (e.g., `http://127.0.0.1:18200/v1` )
`dimension`	Vector dimension (auto-corrected from endpoint)

修改前会将

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`	向量维度（由端点自动修正）

Task 4: Delete Incompatible vectordb Index

任务4：删除不兼容的向量数据库索引

⚠️ Critical: If dimensions differ,
rm -rf vectordb/context
is required. Otherwise
EmbeddingRebuildRequiredError
on startup.

If dimension is unchanged, skip this step.

⚠️ 关键操作： 如果维度发生变化，必须执行
rm -rf vectordb/context
。否则启动时会出现
EmbeddingRebuildRequiredError
。

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

Task 5: Restart openviking-server Inside the Sandbox

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

⚠️ Pitfall:
POST /envs/openviking/stop
+
start
re-runs
start.sh
, which overwrites
ov.conf
with TokenHub credentials. Do not use stop/start.

Instead:

Kill old process from host:
```
kill $PID
```
, then poll for port 1933 release (up to 10s). If SIGTERM doesn't release the port, escalate to
```
kill -9
```
.
Clean up stale lock files:
```
.openviking.pid
```
and vectordb
```
LOCK
```
files.
Start new server via
```
exec
```
API with
```
--max-time 15
```
:

bash

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"]}'

⚠️ 注意事项： 使用
POST /envs/openviking/stop
+
start
会重新执行
start.sh
，该脚本会用TokenHub凭证覆盖
ov.conf
。请勿使用停止/启动方式重启。

正确步骤：

从主机终止旧进程：
```
kill $PID
```
，然后轮询端口1933是否释放（最多10秒）。如果SIGTERM无法释放端口，升级为
```
kill -9
```
。
清理过期锁文件：
```
.openviking.pid
```
和向量数据库
```
LOCK
```
文件。
通过exec API启动新服务器，设置
```
--max-time 15
```
：

bash

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"]}'

Task 6: Verify

任务6：验证

Health check with retry loop (up to 30s): polls
```
GET /health
```
every second until
```
healthy=true
```
or timeout
PID change check: verifies the new server PID differs from the old one (detects port conflict false positives)
Collection dimension check: reads
```
collection_meta.json
```
and confirms
```
Dimension
```
matches target

Log error check: precise grep for

Traceback|ERROR.*Application startup failed|EmbeddingRebuildRequiredError|DataDirectoryLocked

(avoids false positives from "Retrying" info messages)

Rollback on failure: if health check fails or PID unchanged, restores
```
ov.conf.bak
```
and exits with error

带重试循环的健康检查（最多30秒）：每秒轮询
```
GET /health
```
，直到
```
healthy=true
```
或超时
PID变化检查：验证新服务器的PID与旧PID不同（避免端口冲突导致的误判）
集合维度检查：读取
```
collection_meta.json
```
，确认
```
Dimension
```
与目标值匹配

日志错误检查：精准匹配

Traceback|ERROR.*Application startup failed|EmbeddingRebuildRequiredError|DataDirectoryLocked

（避免"Retrying"等信息日志导致的误判）

失败回滚：如果健康检查失败或PID未变化，恢复
```
ov.conf.bak
```
并报错退出

Parameter Confirmation

参数确认

Parameter	Required	Description	Example
`MODEL_NAME`	Yes	Embedding model name	`bge-small-zh-v1.5`
`LLAMA_PORT`	Yes	llama-server port	`18200`
`TARGET_DIMENSION`	Yes	Vector dimension (auto-corrected if wrong)	`512`

bash

undefined

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

bash

undefined

Usage

使用方式

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

undefined

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

undefined

Common Embedding Model Dimensions

常见嵌入模型维度

Model	Dimension	Typical Use
`bge-small-zh-v1.5`	512	Lightweight Chinese embedding
`bge-large-zh-v1.5`	1024	High-quality Chinese embedding
`bge-small-en-v1.5`	384	Lightweight English embedding
`bge-base-en-v1.5`	768	General-purpose English embedding
`Qwen3-Embedding-0.6B`	1024	Qwen3 embedding (TokenHub default)

模型	维度	典型用途
`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默认）

Verification

验证方法

See references/verification-method.md for step-by-step checks and end-to-end acceptance criteria.

Quick verification:

bash

undefined

分步检查和端到端验收标准详见references/verification-method.md。

快速验证：

bash

undefined

1. Server healthy

1. 服务器健康

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

2. 集合维度与目标值匹配

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)

3. 日志中无错误（精准匹配）

grep -ci "Traceback|Application startup failed|EmbeddingRebuildRequiredError|DataDirectoryLocked"
"${SANDBOX_DIR}/process_dir/openviking-server.log"

Expected: 0

预期结果：0

undefined

undefined

Guardrails

防护规则

See references/guardrails.md for the full rules. Key principles:

Always run through job-env-manager — never execute
```
openviking-server
```
directly on the host
Never use stop/start restart —
```
start.sh
```
overwrites
```
ov.conf
```
with TokenHub credentials
Validate before modify — the target endpoint must respond before any config change
Rollback on failure —
```
ov.conf.bak
```
is restored if verification fails

完整规则详见references/guardrails.md。核心原则：

始终通过job-env-manager执行 — 绝不要在主机上直接运行
```
openviking-server
```
绝不要使用停止/启动方式重启 —
```
start.sh
```
会用TokenHub凭证覆盖
```
ov.conf
```
先验证再修改 — 目标端点必须响应后才能修改配置
失败时回滚 — 如果验证失败，恢复
```
ov.conf.bak
```

References

参考文档

Document	Description
config-reference.md	ov.conf embedding section field reference
guardrails.md	Safety rules: sandbox execution, restart sequence, rollback
iam-policies.md	Equivalent access controls (no Huawei Cloud IAM needed)
verification-method.md	Step-by-step verification for each workflow
related-commands.md	Common job-env-manager and curl commands
acceptance-criteria.md	Acceptance criteria for a successful switch
troubleshooting.md	Troubleshooting for common failure scenarios
dataflow-diagram.md	Mermaid data flow diagram
demo/example-input.json	Example input for the switch workflow

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