Embed

---
name: embed
description: Use when building or refreshing the RagKit index for a project knowledge-base/ (e.g. after distill added or updated knowledge points). Trigger /ragkit:embed. Querying instead uses ragkit:query; index health uses ragkit:status.
---

# RagKit Embed

脚本在本插件的 `scripts/` 目录（本 skill 目录的上两级）；用本 skill 的 base directory 把下面的相对路径拼成绝对路径执行。

```sh
sh ../../scripts/run.sh ../../scripts/ragkit.py \
   embed --kb <项目根>/knowledge-base
```

- 增量：默认只重嵌变更 chunk；模型/后端变更或索引损坏时加 `--rebuild`。
- **退出码 3** = 无向量后端：stdout 的 ╭─ RagKit ─╮ 提示块**必须原样转述给用户**（含第三方 API 配置方法与本地模型安装命令，不要改写）；此时词汇/元数据索引已建好，query 可降级使用。
- **默认走云端**（推荐，免下载）：`sh ../../scripts/run.sh ../../scripts/ragkit.py backend set --provider qwen --kb <知识库路径>` + 设置对应密钥环境变量；preset 见提示块（openai / qwen / zhipu / voyage / azure）。**不要主动引导用户下载本地模型**。
- 本地模型是可选手动项（仅离线/零费用场景，下载约 1.2GB，不会自动下载）：仅在用户明确要求离线时才执行 `uv run ../../scripts/ragkit_local_embed.py install`（国内先 `export HF_ENDPOINT=https://hf-mirror.com`）。
- 双后端并存时固定用云端（脚本内置优先级，无需选择）；确要离线可在 `<知识库路径>/.ragkit/config.json` 显式写 `"backend": "local"`。