huawei-cloud-openviking-embedding-switch

OpenViking Embedding Model Switch

概述

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.

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

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

IAM Permission Policies

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.

核心命令 (Core Workflow)

Task 1: Detect Current Configuration

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).

Task 2: Validate Target Embedding Endpoint

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.

Task 3: Modify ov.conf

Backs up ov.conf to ov.conf.bak before modifying. Updates the embedding.dense section:

Task 4: Delete Incompatible vectordb Index

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

If dimension is unchanged, skip this step.

Task 5: Restart openviking-server Inside the Sandbox

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

Instead:

1. 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.
2. Clean up stale lock files: .openviking.pid and vectordb LOCK files.
3. Start new server via exec API with --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"]}'

Task 6: Verify

1. Health check with retry loop (up to 30s): polls GET /health every second until healthy=true or timeout
2. PID change check: verifies the new server PID differs from the old one (detects port conflict false positives)
3. Collection dimension check: reads collection_meta.json and confirms Dimension matches target
4. Log error check: precise grep for Traceback|ERROR.*Application startup failed|EmbeddingRebuildRequiredError|DataDirectoryLocked (avoids false positives from "Retrying" info messages)
5. Rollback on failure: if health check fails or PID unchanged, restores ov.conf.bak and exits with error

Parameter Confirmation

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

Common Embedding Model Dimensions

Verification

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

Quick verification:

# 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

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