1 line
11 KiB
JSON
1 line
11 KiB
JSON
{"repo": "catlog22/maestro-flow", "files": {"guide/embedding-guide.md": {"a8a7498b03f9272b741d708a17b79e3e3e1813ed": {"t": 1785674116.102987, "n": 7561, "h": "7c0623031404097b", "c": "---\ntitle: \"Embedding 模型配置指南\"\n---\n\nMaestro Search 支持基于 Embedding 的语义搜索，通过向量相似度补充 BM25 全文检索，提供更精准的搜索结果。\n\n---\n\n## 概述\n\nMaestro 的 Embedding 系统基于 `@huggingface/transformers`（ONNX 后端），默认使用 `Xenova/multilingual-e5-small` 模型（22M 参数，384 维），支持：\n\n- **智能设备检测**：自动 benchmark CPU vs GPU（DirectML），选择最快后端\n- **批量推理**：可配置 batch size（4-5x 性能提升）\n- **增量索引**：仅重新嵌入新增或变更文档\n- **优雅降级**：transformers 不可用时自动回退到纯 BM25\n\n### 模型大小\n\n| 文件 | 大小 | 说明 |\n|------|------|------|\n| `onnx/model.onnx` | ~448 MB | ONNX 推理模型（fp32） |\n| `tokenizer.json` | ~16 MB | 分词器 |\n| `config.json` | <1 KB | 模型配置 |\n| **合计** | **~465 MB** | 首次使用自动下载 |\n\n模型缓存位置：`<maestro-package>/node_modules/@huggingface/transformers/.cache/Xenova/multilingual-e5-small/`\n\n> **注意**：模型缓存在 `node_modules` 内，`npm install` 后会丢失，需要重新下载。\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\nnpm install @huggingface/transformers onnxruntime-node\n```\n\n### 2. 管理 Embedding（TUI 命令）\n\n```bash\n# 查看状态（模式、模型、缓存、设备、索引）\nmaestro install embedding --status\n\n# 输出示例：\n# Mode: Local (ONNX)\n# Model: Xenova/multilingual-e5-small\n# Cached: Yes\n# Device: gpu/fp16 batch=128\n# GPU: Available\n# Wiki idx: 804 docs\n# Code idx: 7720 nodes\n\n# 下载本地模型（~465 MB）\nmaestro install embedding --download\n\n# 切换到本地模式（从 API 模式切换）\nmaestro install embedding --local\n\n# 重建代码向量索引\nmaestro install embedding --rebuild\n```\n\n### 3. 预热模型\n\n首次运行会自动下载模型（~465 MB），下载过程有进度条提示。\n`maestro install` 在安装完成后也会自动预热模型。\n\n```bash\n# 手动预热\nmaestro install embedding --download\n```\n\n### 4. 手动下载模型（可选）\n\n如果自动下载失败（网络问题、代理限制），可以手动下载模型文件：\n\n```bash\n# 1. 定位缓存目录（在 maestro 安装目录下）\n# Windows: <maestro>\\node_modules\\@huggingface\\transformers\\.cache\\Xenova\\multilingual-e5-small\\\n# Linux/macOS: <maestro>/node_modules/@huggingface/transformers/.cache/Xenova/multilingual-e5-small/\n\n# 2. 创建目录（含 onnx 子目录）\nmkdir -p node_modules/@huggingface/transformers/.cache/Xenova/multilingual-e5-small/onnx\n\n# 3. 下载文件（需要代理的地区请配置 HTTPS_PROXY）\nCACHE=node_modules/@huggingface/transformers/.cache/Xenova/multilingual-e5-small\nHF=https://huggingface.co/Xenova/multilingual-e5-small/resolve/main\n\ncurl -L -o $CACHE/onnx/model.onnx $HF/onnx/model.onnx # ~448 MB\ncurl -L -o $CACHE/tokenizer.json $HF/tokenizer.json # ~16 MB\ncurl -L -o $CACHE/config.json $HF/config.json # <1 KB\ncurl -L -o $CACHE/tokenizer_config.json $HF/tokenizer_config.json # <1 KB\n\n# 4. 验证\nmaestro embedding status\n```\n\n> 也可从镜像源下载（将 `huggingface.co` 替换为 `hf-mirror.com`）。\n\n---\n\n## 外部 API 配置\n\n除本地 ONNX 模型外，Maestro 支持通过外部 API 获取 embedding 向量。配置文件 `~/.maestro/api-embedding.json` 存在时自动启用 API 模式，跳过本地模型加载。\n\n### 配置文件\n\n创建 `~/.maestro/api-embedding.json`：\n\n```json\n{\n \"baseUrl\": \"https://api.siliconflow.cn/v1\",\n \"apiKey\": \"sk-your-api-key\",\n \"model\": \"BAAI/bge-m3\",\n \"dimensions\": 1024,\n \"batchSize\": 64\n}\n```\n\n| 字段 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `baseUrl` | ✅ | — | OpenAI 兼容的 API 端点（需支持 `/embeddings`） |\n| `apiKey` | ✅ | — | API 密钥 |\n| `model` | ✅ | — | 模型名称（如 `BAAI/bge-m3`、`text-embedding-3-small`） |\n| `dimensions` | ❌ | — | 向量维度（部分 API 支持指定输出维度） |\n| `batchSize` | ❌ | `100` | 每次 API 请求的最大文本数 |\n\n### 兼容的 API 服务\n\n任何支持 OpenAI `/v1/embeddings` 接口格式的服务均可使用：\n\n| 服务 | baseUrl | 推荐模型 |\n|------|---------|----------|\n| OpenAI | `https://api.openai.com/v1` | `text-embedding-3-small` |\n| SiliconFlow | `https://api.siliconflow.cn/v1` | `BAAI/bge-m3` |\n| 阿里云百炼 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `text-embedding-v3` |\n| 本地 Ollama | `http://localhost:11434/v1` | `nomic-embed-text` |\n\n### 验证配置\n\n```bash\n# 检查 API 模式状态\nmaestro embedding status\n\n# API 模式输出示例：\n# Mode: API (external)\n# Endpoint: https://api.siliconflow.cn/v1\n# Model: BAAI/bge-m3\n# Dimensions: 1024\n# Batch size: 64\n# Active model: BAAI/bge-m3\n\n# 测试 API 连通性\nmaestro embedding warmup\n\n# 输出：\n# Warming up API embedding (BAAI/bge-m3)...\n# API embedding ready (234ms)\n```\n\n### 切换模式\n\n| 操作 | 命令 / 方法 |\n|------|------|\n| 切换到本地模式 | `maestro install embedding --local` |\n| 切换到 API 模式 | 创建 `~/.maestro/api-embedding.json` |\n| 切换模型 | 修改配置文件中的 `model` 字段 |\n| 重建索引 | `maestro install embedding --rebuild` |\n\n> **注意**：切换模型后首次搜索会触发全量索引重建（模型不同，向量不兼容），后续搜索使用增量更新。\n\n### 代理配置\n\nAPI 模式自动读取代理设置，优先级：\n\n1. 环境变量 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY`\n2. `~/.maestro/cli-tools.json` 中的 `proxy` 配置\n\n### 容错机制\n\n- **自动重试**：429/5xx 错误自动重试 2 次（指数退避 1s→2s→4s）\n- **并行请求**：多批次并发上限 4，加速大量文档的索引构建\n- **降级回退**：API 不可达时自动使用上一次成功构建的索引（而非完全禁用 embedding）\n- **原子写入**：索引文件使用 temp+rename 防止写入中断导致损坏\n\n---\n\n## 本地模型配置\n\n### 设备配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `device` | `cpu` \\| `gpu` | 自动检测 | GPU 可用时自动使用 DML/CUDA |\n| `dtype` | `fp32` \\| `fp16` \\| `q8` \\| `q4` | `fp16`（GPU）/ `fp32`（CPU） | 模型精度 |\n| `batchSize` | number | `128`（GPU）/ `32`（CPU） | 批量推理大小 |\n\n**设备选择策略**：\n\n系统自动检测 GPU（DirectML/CUDA），可用时默认使用 GPU + fp16 以获得最佳吞吐量。可通过环境变量 `MAESTRO_EMBEDDING_DEVICE=cpu` 强制使用 CPU。\n\n### 模型配置\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `DEFAULT_MODEL` | `Xenova/multilingual-e5-small` | 默认多语言模型 |\n| `dimension` | `384` | 向量维度 |\n| `maxTokens` | `512` | 最大 token 长度 |\n\n### RRF 融合参数\n\nMaestro 使用 RRF（Reciprocal Rank Fusion）融合 BM25 和向量搜索结果：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `k` | `60` | RRF 常数（控制排名衰减速度） |\n| `bm25Weight` | `0.6` | BM25 权重 |\n| `vectorWeight` | `0.4` | 向量搜索权重 |\n| `alpha` | `0.4` | 混合融合中 RRF 的权重 |\n\n---\n\n## 使用方式\n\n### 基本搜索\n\n```bash\n# 自动使用 embedding（如果可用）\nmaestro search \"authentication patterns\"\n\n# 显式跳过 embedding（仅 BM25）\nmaestro search \"jwt token\" --no-emb\n```\n\n### Embedding 管理\n\n```bash\n# 查看状态\nmaestro install embedding --status\n\n# 下载/预热模型\nmaestro install embedding --download\n\n# 重建代码向量索引\nmaestro install embedding --rebuild\n\n# 切换本地模式\nmaestro install embedding --local\n```\n\n---\n\n## 索引结构\n\n### 二进制格式\n\nEmbedding 索引使用高效的二进制格式存储（`embedding-index.bin`）：\n\n```\n[metaLen:4][metaJSON][docIdsLen:4][docIdsJSON][vectors:n*dim*4]\n```\n\n- **meta**：模型 ID、维度、构建时间、设备信息\n- **docIds**：文档 ID 数组\n- **vectors**：Float32 向量数组\n\n### 增量更新\n\n索引支持增量更新，仅重新嵌入内容变更的文档：\n\n1. 计算文档内容 MD5 哈希\n2. 对比现有索引的哈希值\n3. 仅对变更文档重新生成向量\n4. 保留未变更文档的向量\n\n---\n\n## 性能优化\n\n### 冷启动优化\n\n| 场景 | 耗时 | 说明 |\n|------|------|------|\n| 首次加载（无 daemon） | ~1800ms | ONNX 模型加载 |\n| daemon 热路径 | ~280ms | 模型已缓存 |\n| BM25-only 降级 | ~280ms | 跳过 embedding |\n\n### Search Daemon\n\nSearch daemon 保持 embedding 模型热缓存：\n\n```bash\n# 启动 daemon\nmaestro search-daemon start\n\n# 查看状态\nmaestro search-daemon status\n```\n\ndaemon 空闲 30 分钟后自动关闭。\n\n### 自动降级策略\n\n当 daemon 不可用时：\n1. 自动降级为 BM25-only 模式\n2. 后台自动启动 daemon\n3. 后续搜索获得 embedding 加速\n\n---\n\n## 环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `HTTPS_PROXY` | HTTPS 代理（用于模型下载） |\n| `HTTP_PROXY` | HTTP 代理 |\n| `ALL_PROXY` | 通用代理 |\n\n---\n\n## 故障排除\n\n### 模型不可用\n\n```bash\n# 检查状态\nmaestro embedding status\n\n# 常见原因：\n# 1. @huggingface/transformers 未安装\n# 2. onnxruntime-node 未安装\n# 3. 网络问题（无法下载模型）\n```\n\n### 索引损坏\n\n```bash\n# 重建索引\nmaestro embedding rebuild\n```\n\n### 性能问题\n\n```bash\n# 查看设备信息\nmaestro embedding status\n\n# 如果 GPU 可用但未使用，检查 onnxruntime-node 版本\nnpm list onnxruntime-node\n```\n\n---\n\n## 相关命令\n\n```bash\n# 搜索命令\nmaestro search <query> [--no-emb] [--json]\n\n# Embedding 管理\nmaestro embedding status\nmaestro embedding warmup\nmaestro embedding rebuild\n\n# Search Daemon\nmaestro search-daemon start\nmaestro search-daemon stop\nmaestro search-daemon status\n```\n\n---\n\n## 技术细节\n\n### E5 模型前缀\n\n本地 E5 模型要求特定前缀：\n- 查询：`query: <text>`\n- 文档：`passage: <text>`\n\n本地模式下系统自动添加此前缀。API 模式下不添加前缀，由 API 服务端处理。\n\n### 余弦相似度\n\n向量搜索使用余弦相似度：\n\n```typescript\ncosineSimilarity(a, b) = dot(a, b) / (norm(a) * norm(b))\n```\n\n对于 <10K 文档，使用暴力搜索（flat search）即可满足性能需求。\n\n### 混合融合算法\n\n最终分数计算：\n\n```\nfinalScore = alpha * rrfNorm + (1 - alpha) * bm25Norm\n```\n\n- `rrfNorm`：RRF 分数归一化\n- `bm25Norm`：BM25 分数归一化\n- `alpha`：控制 RRF 和 BM25 的相对权重\n"}}}} |