huawei-cloud-openviking-embedding-switch

[{"code":"api_key_mention","match":"api_key","path":"SKILL.md"},{"code":"api_key_mention","match":"API key","path":"SKILL.md"},{"code":"env_var","match":"JOB_ENV_MODEL_API_KEY","path":"references/config-reference.md"},{"code":"api_key_mention","match":"api_key","path":"references/config-reference.md"},{"code":"api_key_mention","match":"API key","path":"references/config-reference.md"},{"code":"api_key_mention","match":"API key","path":"references/iam-policies.md"},{"code":"env_var","match":"JOB_ENV_MODEL_API_KEY","path":"references/troubleshooting.md"}]

# Acceptance Criteria

Criteria for a successful embedding model switch.

## Pre-Switch

- [ ] OpenViking environment state is `running` (checked via job-env-manager API)
- [ ] Target llama-server responds to `/v1/embeddings`
- [ ] Dimension measured from the endpoint (not assumed from user input)

## Switch Execution

- [ ] `switch-embedding-model.sh <model_name> <llama_port> <dimension>` exits 0
- [ ] `ov.conf.bak` created before modification
- [ ] `ov.conf` `embedding.dense` matches target: provider, model, api_base, dimension
- [ ] If dimension changed: `vectordb/context` deleted before restart
- [ ] Restart used kill + exec, not stop/start
- [ ] Stale locks (`.openviking.pid`, vectordb `LOCK`) cleaned

## Post-Switch

- [ ] `GET /health` returns `healthy=true` (within 30s)
- [ ] New server PID differs from old PID
- [ ] `collection_meta.json` `Dimension` equals target
- [ ] Log shows no `Traceback`, `Application startup failed`, `EmbeddingRebuildRequiredError`, or `DataDirectoryLocked`
- [ ] A semantic search call returns results with the new model

## Rollback Behavior (if verification fails)

- [ ] `ov.conf.bak` restored
- [ ] Script exits with non-zero code
- [ ] Error reas

# ov.conf Embedding Configuration Reference

## Full ov.conf Structure (Relevant Sections)

```json
{
  "storage": {
    "workspace": "/workspace/data"
  },
  "embedding": {
    "dense": {
      "provider": "openai",
      "model": "bge-small-zh-v1.5",
      "api_key": "not-needed",
      "api_base": "http://127.0.0.1:18200/v1",
      "dimension": 512,
      "batch_size": 64
    },
    "max_concurrent": 3,
    "max_retries": 5
  },
  "vlm": {
    "provider": "openai",
    "model": "glm-5.2",
    "api_base": "https://tokenhub.developer.huaweicloud.com/v2",
    "temperature": 0.0,
    "max_retries": 5,
    "api_key": "..."
  },
  "server": {
    "host": "127.0.0.1",
    "port": 1933
  }
}
```

## embedding.dense Field Reference

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `provider` | string | Yes | Embedding provider type. Use `"openai"` for any OpenAI-compatible endpoint (including llama-server). |
| `model` | string | Yes | Model name as recognized by the endpoint. For llama-server, this must match the `--model` flag or the model filename (without `.gguf`). |
| `api_key` | string | Yes | API key for authentication. For local llama-server, 

# Data Flow Diagram

```mermaid
flowchart TD
    A[Agent: Switch Embedding Model] --> B[Step 1: Detect Current Config]
    B --> C[Step 2: Validate Target Endpoint]
    C --> D{Endpoint reachable?}
    D -- No --> D1[STOP: Start llama-server first]
    D -- Yes --> E[Step 3: Modify ov.conf]
    E --> F[Step 4: Check Dimension Change]
    F --> G{Dimension changed?}
    G -- Yes --> H[Delete vectordb/context]
    G -- No --> I[Skip index deletion]
    H --> I
    I --> J[Step 5: Restart Server]
    J --> J1[Kill old server process from host]
    J1 --> J2[Start new server via exec API]
    J2 --> K[Step 6: Verify]
    K --> K1{Health OK?}
    K1 -- No --> K2[Check troubleshooting.md]
    K1 -- Yes --> K3{Dimension correct?}
    K3 -- No --> K2
    K3 -- Yes --> K4{No errors in log?}
    K4 -- No --> K2
    K4 -- Yes --> L[✅ Switch Complete]

    style D1 fill:#f66,color:#fff
    style L fill:#6f6,color:#fff
    style H fill:#f96
    style J1 fill:#f96
```

## Embedding Request Flow (Runtime)

```mermaid
sequenceDiagram
    participant Client as Client
    participant OV as OpenViking Server<br/>(:1933)
    participant VDB as VectorDB<br/>(vectordb/context)
    participant Llama as l

# Guardrails

Safety rules for the OpenViking embedding model switch skill. These rules are mandatory — violations corrupt the running OpenViking server or its data.

## 1. Sandbox Execution

- **Never run `openviking-server` directly on the host.** All operations go through the job-env-manager REST API (`http://127.0.0.1:8090`).
- All in-sandbox commands use `POST /api/v1/envs/openviking/exec`.
- If the OpenViking environment state is not `running`, do not proceed — report and suggest `POST /api/v1/envs/openviking/start`.

## 2. Restart Sequence

- **Never use `stop` + `start`.** `start.sh` overwrites `ov.conf` with TokenHub credentials on environment restart, silently reverting the embedding configuration.
- The only valid restart is: kill old process → clean stale locks (`.openviking.pid`, vectordb `LOCK`) → start via `exec` API → verify.
- Escalate to `kill -9` only after SIGTERM fails to release port 1933 within ~10s.

## 3. Validation Before Modification

- The target embedding endpoint must respond to `/v1/embeddings` **before** any config change.
- **Never trust user-supplied dimension.** Measure it from the endpoint response (`len(data[0].embedding)`) and auto-correct with

# IAM Policies / Access Permissions

## Overview

This skill switches OpenViking's embedding model via the job-env-manager REST API. It does not access Huawei Cloud services, so no Huawei Cloud IAM policies are required. The permissions below are the equivalent access controls for this environment.

## Minimum Required Permissions

| Resource | Permission | Reason |
|----------|-----------|--------|
| job-env-manager | REST API `http://127.0.0.1:8090` | Query env state, `exec` API for in-sandbox commands |
| OpenViking sandbox | Read/write `ov.conf`, `vectordb/context` | Modify embedding config, rebuild index |
| llama-server sandbox | Access `http://127.0.0.1:${LLAMA_PORT}/v1/embeddings` | Validate target embedding endpoint, measure dimension |
| OpenViking server | Access `http://127.0.0.1:1933/health` | Health verification after restart |
| Host | Execute `curl`, `python3`, `kill` | Script prerequisites |

## Authentication

- **Dev mode (default)**: no API key needed — job-env-manager accepts anonymous access on the host loopback.
- If the environment requires an API key, it must come from environment variables — never hardcode it and never ask the user to type it in chat.

## 

# Related Commands

Common commands for the embedding model switch workflow.

## job-env-manager REST API

| Command | Purpose |
|---------|---------|
| `curl -s http://127.0.0.1:8090/api/v1/envs/openviking` | Get environment details (state, cwd) |
| `curl -s -X POST http://127.0.0.1:8090/api/v1/envs/openviking/start` | Start the OpenViking environment |
| `curl -s -X POST http://127.0.0.1:8090/api/v1/envs/openviking/stop` | **Forbidden for restart** — re-runs start.sh, overwrites ov.conf |
| `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":[...]}'` | Execute a command inside the sandbox |

## Embedding Endpoint

| Command | Purpose |
|---------|---------|
| `curl -s http://127.0.0.1:${PORT}/v1/embeddings -H "Content-Type: application/json" -d '{"model":"${MODEL}","input":"test"}'` | Validate embedding endpoint and measure dimension |

## Server Health and Process

| Command | Purpose |
|---------|---------|
| `curl -s http://127.0.0.1:1933/health` | Check server health |
| `ss -tlnp \| grep 1933` | Check if port 1933 is in use (and which PID) |
| `kill <PID>` / `kill -9 <PID>` | Stop the old server proc

# Troubleshooting

## Problem 1: EmbeddingRebuildRequiredError on Server Startup

**Symptom:**
```
openviking.storage.errors.EmbeddingRebuildRequiredError: Existing collection embedding dimension (1024) does not match current configuration (512).
```

**Cause:** `collection_meta.json` still records the old dimension. vectordb index not fully deleted before restart.

**Fix:**
```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'])")
rm -rf "${SANDBOX_DIR}/data/vectordb/context"
# Then restart the server (Step 5 in SKILL.md)
```

---

## Problem 2: ov.conf Overwritten After Environment Restart

**Symptom:** After `stop` + `start`, `ov.conf` reverts to TokenHub defaults.

**Cause:** `start.sh` overwrites `ov.conf` using `JOB_ENV_MODEL_API_KEY` or `AK`/`SK` env vars.

**Fix:** Do NOT use stop/start. Instead: modify `ov.conf` → kill server from host → start via `exec` API. If stop/start was already used, re-apply Step 3 then Step 5.

---

## Problem 3: exec API "No such process" When Trying to Kill Server

**Symptom:** `kill` via exec API fails with "No such process".

**Cause:** exec API runs in a 

# Verification Method

Step-by-step verification for each workflow of the embedding model switch skill.

## Prerequisite Checks

| Check | Method |
|-------|--------|
| job-env-manager reachable | `curl -s http://127.0.0.1:8090/api/v1/envs/openviking` returns JSON |
| OpenViking env running | Response `state` equals `running` |
| llama-server reachable | `curl -s http://127.0.0.1:${LLAMA_PORT}/v1/embeddings -d '{"model":"${MODEL_NAME}","input":"test"}'` returns an embedding |
| Host tooling | `curl --version` and `python3 --version` succeed |

## Task 1: Detect Current Configuration

| Check | Method |
|-------|--------|
| Sandbox dir obtained | `cwd` from env response is non-empty |
| Current embedding read | `ov.conf` contains `embedding.dense` with provider/model/dimension fields |

## Task 2: Validate Target Endpoint

| Check | Method |
|-------|--------|
| Endpoint reachable | `/v1/embeddings` returns HTTP 200 |
| Dimension measured | `len(d['data'][0]['embedding'])` returns a positive integer |
| Dimension correction | Warning printed if user-supplied `TARGET_DIMENSION` differs from measured value |

## Task 3: Modify ov.conf

| Check | Method |
|-------|--------|
| Backup cr

---
name: huawei-cloud-openviking-embedding-switch
description: |
  Switch OpenViking's embedding model to a local llama-server (or any OpenAI-compatible embedding endpoint) running inside a bwrap sandbox managed by job-env-manager. Handles the full lifecycle: detect current config, validate the target embedding endpoint, modify ov.conf, delete incompatible vectordb index when dimension changes, restart the openviking-server process in the sandbox, and verify the new collection dimension.
  Use this skill when the user wants to: (1) switch the OpenViking embedding model, (2) change the embedding dimension, (3) fix EmbeddingRebuildRequiredError after a dimension mismatch, (4) rebuild the vectordb index after an embedding model change, (5) use a local llama-server for OpenViking embeddings.
  Trigger words: "切换OpenViking embedding", "OpenViking embedding模型", "OpenViking向量化模型", "openviking embedding switch", "change openviking embedding model", "配置openviking embedding", "openviking llama embedding", "bge embedding openviking", "切换向量化模型", "OpenViking模型切换".
tags:
  - openviking
  - embedding
  - llama
  - vectordb
  - job-env-manager
---

# OpenViking Embedding Model Switch

## 概述

Swit