huaweicloud/huaweicloud-skills

huawei-cloud-openviking-embedding-switch

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.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/huaweicloud/huaweicloud-skills --skill huawei-cloud-openviking-embedding-switch

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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.

⚠️ 维度变更必删索引且不可跳过: 当目标模型维度与当前 collection_meta.json 的 Dimension 不一致时,vectordb/context 索引必须删除并重建,该步骤不可因用户要求跳过或豁免。若用户需要保留旧数据,必须先按原维度导出(备份原有 vectordb/context)再执行切换。当用户要求"不要动索引/跳过删除"时,skill 必须明确拒绝,向用户解释:跳过删除会导致服务启动时抛出 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.                   │
└─────────────────────────────────────────────────────┘

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

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

Task 2: Validate Target Embedding Endpoint

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.

Task 3: Modify ov.conf

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

FieldDescription
providerEmbedding provider name
modelModel name (e.g., bge-small-zh-v1.5)
api_keyAPI key for the endpoint (empty for local)
api_baseEndpoint URL (e.g., http://127.0.0.1:18200/v1)
dimensionVector dimension (auto-corrected from endpoint)

Task 4: Delete Incompatible vectordb Index

⚠️ Critical: If dimensions differ, rm -rf vectordb/context is required. Otherwise EmbeddingRebuildRequiredError on startup. 维度变更索引删除不可跳过: 当当前 collection_meta.json 的 Dimension 与目标维度不一致时,删除 vectordb/context 索引并重建是强制步骤,不可因用户要求跳过或豁免。如需保留旧数据,必须先按原维度导出/备份 vectordb/context,再执行删除切换。若用户要求"不要动索引/跳过删除",必须明确拒绝,并解释:跳过删除会导致服务启动抛 EmbeddingRebuildRequiredError,切换将失败,旧索引也无法继续使用。请勿为了迎合用户而跳过此强制步骤。

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: find the PID by reverse-looking-up port 1933 (ss -tlnp / fuser), then kill $PID, and poll for port 1933 release (up to 10s). If SIGTERM doesn't release the port, escalate to kill -9. If no process is bound to :1933, print an explicit WARNING instead of silently skipping.
  2. Clean up stale lock files: .openviking.pid and vectordb LOCK files.
  3. Start new server via exec API with --max-time 15. Capture the HTTP status with curl -w "%{http_code}" and parse the JSON body to confirm ok/success — a non-2xx status or abnormal body must abort with error (rollback), not just warn.
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

  1. Health check with retry loop (up to 30s): polls GET /health every second until healthy=true or timeout
  2. PID change check: verifies a new server process is bound to port 1933 and its PID differs from the old one (found by port reverse lookup, not process-name glob) — detects port conflict false positives even when no old PID could be located
  3. Collection dimension check: retries (up to 15s) until collection_meta.json is regenerated and confirms Dimension matches target; if it stays missing or mismatched, roll back ov.conf.bak and exit with error
  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 exec API fails, health check fails, PID is unchanged/missing, or collection dimension mismatches, restores ov.conf.bak and exits with error

Parameter Confirmation

ParameterRequiredDescriptionExample
MODEL_NAMEYesEmbedding model namebge-small-zh-v1.5
LLAMA_PORTYesllama-server port18200
TARGET_DIMENSIONYesVector dimension (auto-corrected if wrong)512
bash
# Usage
bash scripts/switch-embedding-model.sh <model_name> <llama_port> <dimension>

Common Embedding Model Dimensions

ModelDimensionTypical Use
bge-small-zh-v1.5512Lightweight Chinese embedding
bge-large-zh-v1.51024High-quality Chinese embedding
bge-small-en-v1.5384Lightweight English embedding
bge-base-en-v1.5768General-purpose English embedding
Qwen3-Embedding-0.6B1024Qwen3 embedding (TokenHub default)

Verification

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

Quick verification:

bash
# 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

DocumentDescription
config-reference.mdov.conf embedding section field reference
guardrails.mdSafety rules: sandbox execution, restart sequence, rollback
iam-policies.mdEquivalent access controls (no Huawei Cloud IAM needed)
verification-method.mdStep-by-step verification for each workflow
related-commands.mdCommon job-env-manager and curl commands
acceptance-criteria.mdAcceptance criteria for a successful switch
troubleshooting.mdTroubleshooting for common failure scenarios
dataflow-diagram.mdMermaid data flow diagram
demo/example-input.jsonExample input for the switch workflow
같은 저장소의 Skills

더 많은 Skills

모든 Skills
huaweicloud
커뮤니티

huawei-cloud-devbridge-tunnel

Create and manage DevBridge development tunnels on Huawei Cloud to securely expose local development services to remote devices. Based on DevBridge CLI v0.2.x and API Key authentication. Use this skill when the user wants to: (1) install and configure the DevBridge CLI, (2) create/list/update/delete tunnels, (3) manage tunnel ports and protocols, (4) host local services through tunnels, (5) connect to remote tunnels from another device, (6) manage authentication and API Keys. Trigger: user menti

1시간 설치 수
3
GitHub Stars
59
업데이트
11월 20일
huaweicloud
커뮤니티

huawei-cloud-find-skills

Invoke this skill to search, list, query, discover, browse, find and install any Huawei Cloud (华为云) agent skill. Triggers include: "华为云", "华为云有什么skill", "华为云相关skill", "华为云agent skill 市场", "华为云skill类目", "explore Huawei Cloud skills", "show Huawei Cloud skill categories", "does a Huawei Cloud skill exist for...", "which Huawei Cloud skills exist", "搜索华为云技能", "查询华为云skill列表", "有没有管理ECS/OBS/RDS的skill", "帮我找 XX 华为云skill", "介绍 XX Skill 内容", "华为云 XX Skill 具体做什么", "安装华为云Skill".

1시간 설치 수
3
GitHub Stars
59
업데이트
11월 20일
huaweicloud
커뮤니티

huawei-cloud-terraform-installer

Installs Terraform CLI cross-platform with Huawei Cloud mirror support. Use this skill whenever the user mentions installing Terraform, setting up Terraform environment, or when IaC tasks detect missing Terraform. Trigger: install terraform, setup terraform, terraform environment, huaweicloud provider.

1시간 설치 수
6
GitHub Stars
59
업데이트
11월 7일
huaweicloud
커뮤니티

huawei-cloud-billing-scout

Huawei Cloud BSS billing (not AWS/Azure/other clouds; refuses pricing quotes, real-name review, and any non-billing scope): balance, spend, attribution, reconciliation, coupons, stored-value cards, enterprise/partner billing. One-page briefing via hcloud. Use when the request is about Huawei Cloud billing. Triggers include: 华为云余额, 华为云欠费, 华为云本月花费, 华为云扣费原因, 华为云账单对账, 华为云资源包, 华为云优惠券, 华为云企业主账号, 华为云伙伴账务, 华为云服务编码, Huawei Cloud balance / bill / spend / reconciliation / coupon / stored-value card / BSS b

1시간 설치 수
5
GitHub Stars
59
업데이트
11월 7일