---
title: 配置 Embedding：按检索样本选模型并验证重建
description: 检查向量模型的任务支持、实际输入和索引兼容性，用已知笔记与无答案查询验收配置及模型切换。
image: "https://zengliangyi.com/og/blog/embedding-model-configuration.png"
---

向量维度不能单独决定检索质量，模型名称相同也不能单独证明已有向量与新查询仍兼容。先确认任务、实际输入和测试样本，再配置并检查索引状态。

本文按 [ChatCrystal](/projects/chatcrystal) 提交 [`7642768`](https://github.com/ZengLiangYi/ChatCrystal/tree/764276814e5c5a33ecbfeae63754f74b9261a3a8) 说明配置与切换。它不提供未经实测的星级、价格表或“某个维度一定够用”的结论。

## 检查任务能力和运行边界

[提供方注册表](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/services/providers.ts) 为 Ollama、OpenAI、Google、Azure 和 Custom 提供向量工厂；Anthropic、OrcaRouter 注册项没有这条路径。支持工厂仍需配合实际可用的向量模型，不能填入任意生成模型名称。

本地默认示例是 `nomic-embed-text`；OpenAI 的请求结构可参考 [官方 Embedding 指南](https://developers.openai.com/api/docs/guides/embeddings)。选择时比较目标语言、技术术语、输入长度、响应稳定性、数据发送路径和资源用量。费用与模型可用性在使用时重新核对，不从“云端”或“本地”标签推导精度与成本。

## 理解应用实际送入的文本

[向量服务](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/services/embedding.ts) 拼接标题、摘要、结论、标签和代码描述。手动笔记与 Agent 写回还可加入代码证据、根因、处理方案、错误特征和文件等字段。不能概括成“所有来源一律不包含代码正文”。

代码使用 500 字符作为段落分组目标，不是每块严格的最大长度：单个长段落不会在这里硬切成 500 字符。字符也不等于 token，需检查实际模型的输入限制。字段拼接的顺序不表示实现了可量化的字段权重。

## 从一个可检查的配置开始

默认本机连接上的本地例子如下；若已有向量或活动任务，先阅读确认提示，不要直接绕过：



```bash
crystal   config   set   embedding.provider   ollama  
  crystal   config   set   embedding.baseURL   http://localhost:11434  
  crystal   config   set   embedding.model   nomic-embed-text  
  crystal   config   get  
  crystal   config   test
```



模型必须已经下载，服务必须可访问。Ollama 适配器会追加 `/v1`，这里使用根地址。环境变量提供默认值，已有保存配置可覆盖它们；以 `get` 的实际值和向量测试结果为准。

## 切换模型时区分清空与生成

[配置路由](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/routes/config.ts) 对部分变更给出确认要求。确认 provider 或 model 变更后，清空已有向量与索引，将笔记标为 `pending`；这不自动安排重建任务。先备份并确认新配置可用，再提交：



```bash
curl   --request   POST   http://localhost:3721/api/embeddings/batch  
  curl   http://localhost:3721/api/queue/status
```



批量接口只选择 `pending`、`failed`、`syncing` 的笔记，并跳过已有活动任务。`queued` 是入队数，不是成功数；不能用空队列代替笔记状态核验。详情与状态命令见 [两类模型与重建验收](/blog/llm-and-embedding-separation)。

仅删除 `vectra-index` 目录不会把 `done` 笔记改为待处理，随后批量请求可能入队零条。地址、模型同名版本或输入策略变更也不一定触发配置路由的清空条件。需要重新生成单篇时，[笔记接口](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/routes/notes.ts)提供同步处理入口，替换实际笔记 ID 后使用：



```text
POST http://localhost:3721/api/notes/<note-id>/embed
```



这是重新生成向量，不是重写笔记正文。生产库操作前确认任务与备份，完整核对受影响的笔记范围。

## 用自己的问题验收

准备已知答案、同义表述、精确错误名和无答案查询，记录目标笔记是否出现、返回顺序、误匹配与响应失败。笔记状态为 `done` 后，再读取结果正文和适用条件。

更高维度可能增加存储和计算，但不能据此认定更准确。对同一组笔记与查询比较结果，才能解释本次配置是否适合知识库。检索请求与评分边界见 [语义搜索流程](/blog/semantic-search-workflow)，本地服务验收见 [Ollama 流程](/blog/ollama-local-workflow)。

分享：

##  相关文章

[##  Embedding 横评方法：固定笔记与查询，比较实际命中

用人工标注的查询和独立索引比较本地与云端 Embedding，核对重建状态、命中质量和资源成本。          曾亮懿       2026年10月4日      阅读约 3 分钟

#ChatCrystal

#Embedding

#评测](/blog/embedding-retrieval-evaluation)    [##  AI 对话格式差异：事件、快照与跨库消息定位

对照五个固定适配器，区分 JSONL 容器、事件语义与 SQLite 键布局，用两个内存数据库观察消息索引、孤立数据和未知版本。          曾亮懿       2026年10月7日      阅读约 4 分钟

#ChatCrystal

#Node.js

#SQLite](/blog/ai-conversation-format-divergence)    [##  AI 对话管理方案：四种存储路径与迁移验收

比较 Claude Code、Cursor、Copilot、Trae 的固定适配器输入，区分原始副本、可读导出与知识库，并用合成清单验证身份和信息保留。          曾亮懿       2026年10月7日      阅读约 4 分钟

#ChatCrystal

#Node.js

#SQLite](/blog/ai-conversation-management-options)

##  从文章到代码

到我的 GitHub 看看 ChatCrystal、开发者工具和日常学习记录，欢迎交流实现细节。

[访问我的 GitHub](https://github.com/ZengLiangYi)

```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "ZengLiangYi Blog",
  "alternateName": [
    "Zeng Liangyi",
    "ZengLiangYi",
    "zengliangyi.com"
  ],
  "url": "https://zengliangyi.com",
  "description": "曾亮懿的个人网站。记录 AI Native 探索、开发者工具与全栈产品实践。"
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "配置 Embedding：按检索样本选模型并验证重建",
  "description": "检查向量模型的任务支持、实际输入和索引兼容性，用已知笔记与无答案查询验收配置及模型切换。",
  "url": "https://zengliangyi.com/blog/embedding-model-configuration/",
  "image": "https://zengliangyi.com/images/blog/embedding-model-configuration.svg",
  "datePublished": "2026-10-03T00:00:00.000Z",
  "dateModified": "2026-10-03T00:00:00.000Z",
  "author": {
    "@type": "Person",
    "name": "曾亮懿",
    "url": "https://zengliangyi.com/about"
  },
  "publisher": {
    "@type": "Organization",
    "name": "ZengLiangYi Blog",
    "logo": {
      "@type": "ImageObject",
      "url": "https://zengliangyi.com/favicon-96x96.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://zengliangyi.com/blog/embedding-model-configuration/"
  }
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "首页",
      "item": "https://zengliangyi.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "文章",
      "item": "https://zengliangyi.com/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "配置 Embedding：按检索样本选模型并验证重建",
      "item": "https://zengliangyi.com/blog/embedding-model-configuration/"
    }
  ]
}
```