跳到正文
曾亮懿 ZengLiangYi Blog

大模型与 Embedding 解耦架构:模型职责隔离设计

为什么要将文本生成大模型(LLM)与向量 Embedding 模型解耦配置:应对第三方网关缺省向量接口的场景,隔离连通性测试、密钥轮换与向量索引重建风险。

阅读约 5 分钟
目录 展开 收起

两处设置都叫“模型”,不代表它们可以填同一个名字。生成笔记需要语言模型输出内容,语义搜索需要 Embedding 接口输出数值向量。排查配置问题时,应先确认任务和返回类型,再检查提供方与模型名。

本文核对 ChatCrystal 提交 7642768 的配置与提供方实现,不给出跨提供方的模型质量排名。

同一输入,两种输出

  • 文本生成:输入一段问题与排查对话,输出标题、摘要、结论等内容,用于生成笔记和发现关系。
  • Embedding:输入用于检索的笔记文本或查询,输出数值向量,用于建立索引和查询相似候选。

OpenAI 的 Embedding 文档展示了专门的向量请求与响应。不能把生成接口返回的一段文字直接塞进向量索引,也不能仅因为某个模型名称含有 GPT、Claude 或 Qwen,就推断其支持哪些任务;要检查实际模型与接口能力。

生成接口也并非都叫 /v1/chat/completions。提供方可能使用 Responses 或自己的协议;ChatCrystal 的适配代码决定具体调用方式。这里的配置分离来自任务契约,不是对所有模型架构作绝对判断。

应用中确实有两套配置

配置代码分别保存 llm 与 embedding,各自包含 provider、baseURL、apiKey、model。环境变量提供默认值,已有 config.json 中的模型配置会覆盖对应默认值。因此,修改环境变量后,也要确认服务实际加载的结果。

crystal config get
crystal config test

get 显示模型名、端点和是否设置密钥,不显示密钥正文。test 分别测试两条路径。看见 LLM 成功,不能据此忽略 Embedding 的失败信息。

用本地组合说明配置关系

下面是一个明确选择两种任务的示例,不是最快或最准确的模型推荐:

crystal config set llm.provider ollama
crystal config set llm.baseURL http://localhost:11434
crystal config set llm.model qwen2.5:7b
crystal config set embedding.provider ollama
crystal config set embedding.baseURL http://localhost:11434
crystal config set embedding.model nomic-embed-text

前提是相应模型已下载,服务正在运行。当前 Ollama 适配器会在配置地址后追加 /v1,因此这里填写服务根地址,不再重复添加 /v1。Ollama 兼容接口说明可用于核对生成与向量端点;兼容一个接口,不代表服务支持该接口的所有功能。

当前 ChatCrystal 的 Anthropic 与 OrcaRouter 条目没有创建 Embedding 模型的实现;需要为检索选择另一个支持该任务的条目。这是本版本应用适配的边界,不能据此断言某个厂商永远不会提供向量服务。

混合本地 Embedding 与远端语言模型也可作为配置方案。这样笔记或查询的向量计算可以留在本机,但发送给远端生成模型的材料仍会离开本机;详见数据流与隐私边界。

连接测试应怎样解释

测试路由会执行短文本生成,再调用 Embedding 处理测试字符串。它分别捕获错误,并用 connected 表示两项结果。HTTP 响应成功不等于两项连接都成功;CLI 的输出中出现失败项时,也不能仅凭进程退出码判断通过。

现象 优先检查
连接被拒绝或超时 模型服务是否启动、端点是否可达、地址属于哪个进程
404 或模型不存在 路径是否正确、模型 ID 是否可用、模型是否支持本次任务
授权失败 对应配置是否有有效密钥、账户是否允许调用
短测试成功,摘要失败 实际输入长度、结构化输出能力、运行资源和返回错误

错误码只是线索,404 不会自动证明“把 LLM 填进了 Embedding”。保留完整错误和对应配置,分别排查两条调用链。

更换向量模型还涉及已有索引

新旧向量不能只因为维度相同就直接混用。模型、版本及输入处理方式改变后,表示空间可能不同。需要让笔记向量与查询向量使用匹配的配置,重新检查检索质量。

ChatCrystal 对部分 Embedding 配置变更会返回确认要求与警告。确认更换提供方或模型后,当前实现会清空已有向量及索引,把笔记标为 pending,但不会自动将重建任务入队。先备份并读懂提示,再决定是否带 --confirm;不要把配置更新成功当成重建已开始。

在新的模型配置测试通过后,本机模式可通过批量向量接口显式提交待处理笔记:

curl --request POST http://localhost:3721/api/embeddings/batch

返回的 queued 是入队数量,不是已经完成的数量。可读取任务快照,并用列表中实际的笔记 ID 查看详情:

curl http://localhost:3721/api/queue/status
crystal --json notes list
crystal --json notes get <note-id>

队列响应在 data 中提供状态;笔记详情的 JSON 直接包含 embedding_status。笔记为 done 后,再验证已知答案和不应匹配的查询。pending 或 syncing 表示尚未完成,failed 需要结合任务错误排查。不能只看队列暂时为空就判断所有笔记成功。修改 baseURL 等其他设置时,也应检查旧索引是否仍与新查询匹配。

第一次使用可以先完成安装与单条笔记验证。测试一条已知答案的查询,再加入一个不应匹配的查询,才能同时观察成功与失败路径。

分享:

相关文章

Vectra 本地向量搜索实战:元数据过滤与索引持久化

在 Node.js 中使用 Vectra 0.15 构建本地文件向量检索:通过确定性临时目录实验验证余弦相似度排序、元数据前置过滤、索引重开持久化与中断更新清理。

曾亮懿 曾亮懿
阅读约 4 分钟
#ChatCrystal #AI #Node.js #向量搜索

深入 Vectra 向量索引底层:元数据存储与增量缓存

深入剖析 Vectra 0.15 本地向量索引底层实现:拆解磁盘 JSON 索引布局、外部元数据文件读取、写入中断后的残留清理,以及多实例内存缓存一致性边界。

曾亮懿 曾亮懿
阅读约 4 分钟
#ChatCrystal #Node.js #SQLite #向量搜索

本地 Embedding 模型选型指南:样本校准与索引重建

选型与配置本地及云端文本 Embedding 向量模型:核对检索任务支持、实际分块输入与向量维度兼容性,在切换模型后安全完成全量向量索引重建与命中验收。

曾亮懿 曾亮懿
阅读约 3 分钟
#ChatCrystal #Embedding #向量搜索

从文章到代码

到我的 GitHub 看看 ChatCrystal、KeelDesk、n8n 工作流和日常学习记录,欢迎交流实现细节。