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 環境がデプロイ済みで実行中であること（state = 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 に記載されています。

コアコマンド（コアワークフロー）

タスク 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 セクション（プロバイダー、モデル、次元数）を取得します。

タスク 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 が再実行され、ov.conf が TokenHub の認証情報で上書きされます。stop/start は使用しないでください。

代わりに、次の手順を実行します。

1. ホストから古いプロセスを終了します：kill $PID を実行し、ポート 1933 が解放されるまで（最大 10 秒）ポーリングします。SIGTERM でポートが解放されない場合は、kill -9 に切り替えます。
2. 古いロックファイルをクリーンアップします：.openviking.pid と vectordb の LOCK ファイルを削除します。
3. --max-time 15 を指定して exec API 経由で新しいサーバーを起動します。

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 が古いものと異なることを確認します（ポート競合による誤検出を防ぎます）。
3. コレクションの次元数を確認します：collection_meta.json を読み取り、Dimension が対象の値と一致することを確認します。
4. ログのエラーを確認します：Traceback|ERROR.*Application startup failed|EmbeddingRebuildRequiredError|DataDirectoryLocked を正確に grep します（「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 を直接実行しないでください
• stop/start による再起動は行わない — 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	切り替えワークフローの入力例