DocsGPT 嵌入模型Embedding Models完全指南本地 ONNX、OpenAI 与远程服务配置实战【免费下载链接】DocsGPTPrivate AI platform for agents, assistants and enterprise search. Built-in Agent Builder, Deep research, Document analysis, Multi-model support, and API connectivity for agents.项目地址: https://gitcode.com/GitHub_Trending/do/DocsGPT本篇指南围绕 DocsGPT 的嵌入模型体系展开先讲清嵌入模型在语义检索链路中的角色再覆盖 DocsGPT 开箱即用的四类嵌入模型支持本地 FastEmbed/ONNX、OpenAI、Azure OpenAI、OpenAI 兼容远程服务的完整配置方法并结合application/vectorstore下的源码与application/scripts下的运维脚本深入剖析模型注册表model registry、查询嵌入委托worker delegation、批处理参数、维度一致性与reembed迁移脚本的实现细节。读完之后你能够独立完成嵌入模型的选择、.env配置、离线部署预取、跨模型迁移以及自定义模型注册。一、什么是嵌入模型为什么 DocsGPT 离不开它嵌入模型Embedding Model是一类将文本转换为数值向量的语言模型。这些向量embedding捕获了文本的语义含义可以把它们理解为把词语和句子翻译成计算机可以用数学处理的语言在向量空间中语义相近的文本对应距离更近的向量。DocsGPT 依赖嵌入模型完成两项关键任务语义搜索Semantic Search上传文档时DocsGPT 用嵌入模型为每个文档分块chunk生成向量并写入向量库。提问时查询文本同样被转换为向量DocsGPT 在向量库中执行语义搜索找出与查询向量最相似的分块。这意味着检索依据的是问题与文档的含义匹配而不只是关键词命中。文档理解Document Understanding嵌入帮助 DocsGPT 理解文档的底层含义即使检索到的分块里没有问题的原词也能给出准确、有上下文的回答。本质上嵌入模型是 DocsGPT 把人类语言的细微差别与你文档中的相关信息连接起来的桥梁。在代码层面这条链路收敛于统一接口embed_query单条查询、embed_documents批量文本和dimension向量宽度。无论底层是本地 ONNX、OpenAI API 还是远程服务BaseVectorStore 的各类向量库只面向这个接口编程这正是 DocsGPT 能自由切换嵌入后端的架构前提。二、开箱即用的嵌入模型支持四种运行模式DocsGPT 的嵌入支持分四种模式全部由.env中的EMBEDDINGS_*配置项驱动定义见 settings.py模式关键配置运行位置本地模型FastEmbed / ONNX RuntimeEMBEDDINGS_NAME设为注册表名称或 Hugging Face 仓库 id进程内或委托给 workerOpenAI EmbeddingsEMBEDDINGS_NAMEopenai_text-embedding-ada-002API_KEYOpenAI 云端Azure OpenAI Embeddings在 Azure OpenAI 配置基础上加AZURE_EMBEDDINGS_DEPLOYMENT_NAMEAzure 部署远程 OpenAI 兼容服务EMBEDDINGS_BASE_URLllama.cpp / vLLM / TEI / 托管服务等本地模型FastEmbed 与 ONNXDocsGPT 的本地嵌入统一通过 FastEmbed 运行基于 ONNX Runtime不依赖 PyTorch 全家桶。这意味着FastEmbed 内置的任何模型都能直接使用任何在onnx/model.onnx路径下附带 ONNX 导出的 Hugging Face 仓库都能工作——这覆盖了大多数流行的 sentence-transformers 仓库只有 PyTorch 权重的仓库无法加载——这类模型应通过EMBEDDINGS_BASE_URL以远程服务方式提供。默认模型的演进逻辑写在 settings.py 的注释里EMBEDDINGS_NAME的代码默认值仍是旧模型huggingface_sentence-transformers/all-mpnet-base-v2因为从未显式设置过该变量的存量部署的索引就是用它建的新安装则由 setup 脚本与环境变量模板指向ibm-granite/granite-embedding-311m-multilingual-r2。存量部署切换到 granite 需要先改配置再运行重嵌入脚本见第七节。模型注册表单一事实来源所有「DocsGPT 认识的模型」集中在 model_registry.py 的MODELS元组中每个EmbeddingModel条目一次性声明维度、上下文窗口、池化方式、归一化、运行器provider、HF 仓库与 ONNX 文件。本地运行器、远程客户端、schema 引导和分块器读的都是同一份条目注册名称可带别名维度上下文窗口池化ONNX 文件huggingface_sentence-transformers/all-mpnet-base-v2别名all-mpnet-base-v2等768384meanonnx/model.onnxibm-granite/granite-embedding-311m-multilingual-r2新安装默认76832768clsonnx/model_quint8_avx2.onnxibm-granite/granite-embedding-97m-multilingual-r238432768clsonnx/model_quint8_avx2.onnxopenai_text-embedding-ada-002provider 为openai15368191mean—远程 API几点从源码可以确认的事实两个 granite 模型运行的是int8 量化的 ONNX 图约 313 MB对比 fp32 的 1247 MB因此与同模型的 fp32 索引不逐位可比模块 docstring 中实测短文本余弦约 0.96检索排序不变注册表未知名称不是错误resolve()返回None后调用方会把该名称当作 Hugging Face 仓库处理——这正是配置任意模型的用户所期望的行为未识别模型的维度回退为DEFAULT_EMBEDDING_DIMENSION 768避免静默改变既有表结构。三、配置本地模型在.env中把EMBEDDINGS_NAME设为注册表名称或 Hugging Face 仓库 idEMBEDDINGS_NAMEibm-granite/granite-embedding-311m-multilingual-r2模型在首次使用时下载并缓存用EMBEDDINGS_CACHE_DIR控制缓存位置。不存在需要手工填充的model/目录文件系统路径也不会被接受为模型名。未知仓库的元数据自动读取对注册表之外的仓库DocsGPT 会读取仓库自身的 sentence-transformers 元数据文件见 embeddings_local.py 的_describe_from_repo从1_Pooling/config.json判断池化方式pooling_mode_cls_token→ clspooling_mode_mean_tokens→ mean从modules.json判断是否 L2 归一化存在Normalize模块才归一化——缺席是事实而非缺失数据点积类模型若被强行归一化会改变排序若两个文件都声明不了则假定 mean 池化 L2 归一化并记录 warning——此时可用EMBEDDINGS_POOLING取值cls或mean和EMBEDDINGS_NORMALIZE显式钉住真实值。这两个覆盖项在_apply_overrides中对任何来源的 spec 都优先生效。这里值得强调一个源码注释里的教训mean 池化一个 CLS 模型产出的向量与正确向量余弦约 0.95——「看起来能用」但足以劣化检索且全程静默。这就是 DocsGPT 坚持从仓库元数据读取池化方式、而不是猜的原因。Dense 投影层模型在启动时被拒绝带 Dense 投影层的模型例如sentence-transformers/LaBSE会在加载时抛出RuntimeError被拒绝FastEmbed 只跑 transformer 主干加池化投影层被跳过后向量既宽度错误、也处于不同空间。正确做法是换无投影层的模型或用EMBEDDINGS_BASE_URL以远程方式服务该模型。离线 / 气隙环境构建期预取离线安装应在构建或部署阶段预取模型python -m application.scripts.prefetch_models.prefetch_models.py 默认抓取「旧默认 新默认」两个模型升级部署继续用 mpnet 直到运行reembed新装则直接用 granite也支持传参只取子集如python -m application.scripts.prefetch_models granite-311m。未识别的名称会直接SystemExit报错——因为构建时的静默跳过会变成离线主机运行时的下载失败。相关行为有 test_prefetch_models.py 覆盖。其他可调参数EMBEDDINGS_THREADS本地 ONNX 运行器的 intra-op 线程数默认 None用满所有核心。设置注释指出其扩展是次线性的同样的核心上「多个单线程 worker」往往优于「一个多线程进程」EMBEDDINGS_CACHE_DIRFastEmbed 模型工件缓存目录Docker 镜像构建时在此预热。四、使用 OpenAI / Azure OpenAI 嵌入使用 OpenAI 的text-embedding-ada-002需要把EMBEDDINGS_NAME设为openai_text-embedding-ada-002并确保 OpenAI API key 已通过API_KEY配置非 Azure 场景。.env示例LLM_PROVIDERopenai API_KEYYOUR_OPENAI_API_KEY # Your OpenAI API Key EMBEDDINGS_NAMEopenai_text-embedding-ada-002实现位于 embeddings_openai.py基于官方openaiSDK要点当OPENAI_API_BASE、OPENAI_API_VERSION和AZURE_DEPLOYMENT_NAME三者齐全时自动切换AzureOpenAI客户端嵌入使用的 Azure 部署名取自AZURE_EMBEDDINGS_DEPLOYMENT_NAME由 base.py 的build_local_embeddings在构造实例时注入API key 解析顺序为显式参数 →EMBEDDINGS_KEY→OPENAI_API_KEY未配置 key 时用占位符sk-no-key保证客户端可构造Azure 走自身部署凭据响应按index排序后返回保证向量顺序与输入一致。注意注册表里该模型的 provider 是openai走的是 API 调用而非本地推理prefetch_models会明确跳过它“served remotely, nothing to cache”。五、远程OpenAI 兼容嵌入服务自托管嵌入服务、或任何暴露 OpenAI 风格嵌入 API 的供应商llama.cpp、vLLM、TEI、托管服务商都通过EMBEDDINGS_BASE_URL接入。一旦设置它所有嵌入调用入库与查询都会以 OpenAI 格式发送到{EMBEDDINGS_BASE_URL}/v1/embeddings本地模型不再运行EMBEDDINGS_BASE_URLhttp://localhost:8080 # 你的 OpenAI 兼容嵌入服务 EMBEDDINGS_NAMEyour-model-name # 作为请求中的 model 字段发送 EMBEDDINGS_KEYYOUR_API_KEY # 可选作为 Bearer token 发送参数说明EMBEDDINGS_BASE_URL—— 远程服务基础 URL设置即切换进入远程嵌入模式EMBEDDINGS_NAME—— 作为每次请求的model字段转发EMBEDDINGS_KEY—— 可选 Bearer token直接用 OpenAI 时可从API_KEY复制过来。该模式由 base.py 中的RemoteEmbeddings类实现实例按基础URL_模型名缓存在EmbeddingsSingleton中。防止超大输入被拒EMBEDDINGS_MAX_INPUT_TOKENS某些远程服务尤其 llama.cpp会对超过其物理批大小的单条输入直接返回500。设置EMBEDDINGS_MAX_INPUT_TOKENS可在发送前把每条输入裁剪到固定 token 数EMBEDDINGS_MAX_INPUT_TOKENS512设置后每条输入被截断到该 token 数超出部分丢弃设计上即有损。通常不需要设置。当EMBEDDINGS_NAME指向 DocsGPT 认识的模型时其上下文窗口会被自动采用且计数使用该模型自己的 tokenizer限制与计数同单位。只在两种情况下需要显式设置服务端提供的是 DocsGPT 不认识的模型或你故意想用一个低于模型自身上限的限制。源码中这条逻辑RemoteEmbeddings._resolve_input_limit有一个细致的边界EMBEDDINGS_NAME未显式设置时不施加任何限制。因为对远程服务而言模型名只是转发的model字段一个没人主动选过的默认值比如遗留的 mpnet仅 384 token 窗口不应被当作对你服务端的描述——否则每条分块会被静默砍掉大半。_embeddings_name_is_explicit()专门用「值是否偏离 settings 默认值」而非 pydantic 的model_fields_set来判断后者连 setup 脚本无条件写入的遗留值也算“已设置”。当模型 tokenizer 不可用时计数回退到 tiktoken此时限制值应留有余量以吸收两种 tokenizer 的偏差截断发生时记录 warningTruncating remote embeddings input from X to Y tokens (Z dropped)。六、模型运行在哪查询嵌入委托给 worker本地嵌入模型每个进程要占用数百 MB 常驻内存而 API 每处理一条查询都要嵌入一次——默认部署下 API 会与 worker 各持有一份模型。EMBEDDINGS_DELEGATE_TO_WORKER默认true把这部分工作移到 Celery workerAPI 通过 broker 把文本发过去、取回向量自身不持有模型。settings.py 注释给出的实测数据API 进程从约 657 MB 降到约 284 MB查询嵌入的代价是一次 broker 往返prefork worker 上约 60 ms。队列消费是硬要求启用委托后检索依赖有 worker 消费EMBEDDINGS_QUEUE默认embeddings队列。裸celery worker不带-Q会顺带消费它但用显式-Q启动的 worker 必须把该队列列进去——仓库自带的 Compose 与 Kubernetes 清单为此运行-Q docsgpt,parsing,embeddings。漏掉它每次搜索都会阻塞EMBEDDINGS_DELEGATE_TIMEOUT默认 60 秒后返回一个没有检索上下文的答案而不抛异常。故障探测与冷却embeddings_delegated.py 中的DelegatedEmbeddings用两层保护把「worker 不存在」的发现成本压到一次超时失败冷却闩30 秒一次派发失败后后续请求在冷却窗口内直接快速失败避免一次检索在扇出层和各向量库回退路径上各付一次全量超时并发探针门失败发生前已在并发途中的请求由「探针」机制协调——只有一个调用者付全量EMBEDDINGS_DELEGATE_TIMEOUT其余最多等 2 秒_PROBE_WAIT就跟随结论。注释里说明了极端情形出厂 60 秒超时 × 96 个 WSGI 线程同时阻塞会连健康检查都无法响应一次派发成功后_verified置位后续所有调用者直通 broker不再轮流“证明”worker 存活worker 一旦再次失败该结论随失败一并失效任务结果在get()后立即forget()释放 Redis 中约 17 KB 的结果缓存与 pub/sub 订阅worker 内部Celery 任务执行中调用嵌入时直接走本进程模型——委托给自己会在任务后面排队等待自己因此 worker 进程按需加载并缓存一份本地模型。隔离查询延迟与生产建议共享同一个 worker 意味着查询与入库共享并发查询可能排在一个长解析任务后面。需要隔离查询延迟时单独跑一个专用 workercelery -A application.app.celery worker -Q embeddingsAPI 不跑 worker 时设EMBEDDINGS_DELEGATE_TO_WORKERfalse模型会改在 API 进程内加载。生产环境更推荐EMBEDDINGS_BASE_URL真正的嵌入服务把模型从 API和worker 两边都移除且用一次网络调用替代 broker 往返。七、嵌入维度必须保持一致与 reembed 迁移每个嵌入模型产出固定维度的向量向量库按该维度建表。把EMBEDDINGS_NAME改成不同维度的模型与既有索引不兼容——FAISS 与 LanceDB 会抛维度不匹配错误pgvector/Qdrant 的表也按原维度建好。需要换模型时必须重新入库re-ingest让索引按新维度重建GraphRAG 的图表同样按创建时的嵌入维度定宽也在受影响范围内。相同维度 ≠ 相同模型维度检查只是防索引损坏的护栏不是换模型安全的保证。同为 768 维的all-mpnet-base-v2与granite-embedding-311m-multilingual-r2互换时什么错都不会报但此后每条查询都由新模型嵌入与库中旧模型空间的向量比对——不会失败只是检索质量悄悄劣化。因此同宽度模型切换也必须重嵌入python -m application.scripts.reembed在修改EMBEDDINGS_NAME之后、对外提供查询之前运行。granite 迁移的完整背景见仓库文档 Upgrading。reembed 脚本的工作方式.reembed.py 从向量库中已有的分块文本重建向量不重新下载、解析或分块任何东西。支持面与关键行为SUPPORTED_STORES (pgvector, faiss)pgvector逐页读取按id键控分页而非OFFSET页边界在更新期间保持稳定、逐事务UPDATE向量列——行只被更新而不删插中断的运行保留全部分块、下次重做该批。注释给出了逐页的原因默认分块大小下一个源约 20 万条分块全量物化为字符串约 1.6 GB在 4 GiB 容器里连同模型一起持有足以被 OOM killFAISS索引是扁平数组只能重建——所有新向量在触碰旧索引之前全部算完嵌入期间中断旧索引原封不动save_local先写临时路径再移动就位重建保留既有 chunk idGraphRAG 的graph_node_chunks行与客户端持有的 id 都指向它们维度变化FAISS 由脚本按新宽度重建索引pgvector 的向量列在创建时就定宽维度变化仍需重新入库对应源GraphRAG开启GRAPHRAG_ENABLED时脚本同时重写graph_nodes.name_embedding——这些向量是每次图遍历的种子留在旧模型空间会让图检索以同样静默的方式劣化。重写用的是已存储的graph_nodes.name无需 LLM 重新抽取完成后把sources.model更新为新模型名避免启动时的模型不匹配检查误报。命令行参数python -m application.scripts.reembed --dry-run # 只报告不写任何东西 python -m application.scripts.reembed # 重嵌全部源 python -m application.scripts.reembed --sources a,b # 只处理这些源 # 另有 --batch-size默认 64每批嵌入/事务的分块数与 -v/--verbose两个实现细节值得注意main()会先从app_metadata解析嵌入模型固定值resolve_embeddings_pin否则把模型钉在 granite 但环境里没写EMBEDDINGS_NAME的标准 K8s 部署会被用遗留默认模型整体重嵌脚本还会主动关闭EMBEDDINGS_DELEGATE_TO_WORKER——批处理作业每批付一次 broker 往返毫无意义进程内加载模型还能在模型不可加载时给出真实报错。失败源会被收集结束时提示--sources 失败列表重试退出码非零。相关测试见 test_reembed.py 与 test_reembed_pgvector_live.py。八、两个容易混淆的批处理参数EMBEDDINGS_BATCH_SIZE默认 32——每个存储事务的分块数也是对远程嵌入 API 的每请求条数。调大意味着更少的往返与更少的事务EMBEDDINGS_MODEL_BATCH_SIZE默认 1——本地模型单次前向传播处理的分块数。对本地模型更大的批不是更快。ONNX 需要矩形张量一次前向里的每条输入都要 padding 到其中最长的浪费随分块长度的平方增长。settings.py 的注释记录了 1250 token 默认分块下 32 批峰值 6.6 GB 对比 1 批 2.9 GB 的实测。在 30 文档入库1250 token 默认分块场景的实测数据EMBEDDINGS_MODEL_BATCH_SIZE嵌入耗时峰值 RSS32154 s7.7 GB876 s5.0 GB476 s3.6 GB274 s2.3 GB153 s1.5 GB只有当分块短且长度均匀时才值得调大。embeddings_local.py 的embed_documents还做了一件减少 padding 浪费的事批量分块先按长度排序分组再送入 ONNX最后恢复原始顺序返回调用方 zip 文本时不受影响——同长度文本排在一起padding 只浪费一点点。此外_pad_to_longest_in_batch会解除 mpnet 的tokenizer.json里写死的length: 128固定 padding否则批次张量不齐、ONNX 构建失败。九、为其他嵌入模型添加支持要教 DocsGPT 认识一个新模型——让它带着已知的池化方式、维度与上下文窗口而不是靠推断——在 model_registry.py 的MODELS中新增一个EmbeddingModel条目即可。该注册表是本地运行器、远程客户端、schema 引导与分块器共同读取的单一事实来源。具体而言理解 base.py 中的两个核心类有助于扩展RemoteEmbeddings/EmbeddingsWrapper/OpenAIEmbeddings把不同嵌入实现包装成 DocsGPT 依赖的统一embed_query/embed_documents/dimension接口原文档称之为EmbeddingsWrapper的包装职责当前代码中由这三个类分场景承担EmbeddingsSingleton管理嵌入实例的创建与获取按模型名或基础URL_模型名缓存共享实例get_embeddings()是统一入口——先判断是否远程EMBEDDINGS_BASE_URL再判断是否 worker 委托EMBEDDINGS_DELEGATE_TO_WORKER最后才落到本地/OpenAI 实例。理解这些类与现有实现后你几乎可以为任何嵌入模型库创建自定义集成而注册一个新条目时只需补齐name/dimension/max_input_tokens/pooling/normalize/provider/repo/onnx_file/aliases字段全链路即刻生效。十、配置速查表环境变量默认值作用EMBEDDINGS_NAMEhuggingface_sentence-transformers/all-mpnet-base-v2新装由模板指向 granite嵌入模型名/仓库 id远程模式下作为model字段转发EMBEDDINGS_BASE_URLNone设置即启用远程 OpenAI 兼容嵌入EMBEDDINGS_KEYNone远程/嵌入专用 Bearer tokenEMBEDDINGS_MAX_INPUT_TOKENSNone每条远程嵌入输入截断到 N tokenEMBEDDINGS_BATCH_SIZE32每存储事务/每远程请求的分块数EMBEDDINGS_MODEL_BATCH_SIZE1本地模型每前向传播的分块数EMBEDDINGS_THREADSNone本地 ONNX intra-op 线程数EMBEDDINGS_CACHE_DIRNoneFastEmbed 模型缓存目录EMBEDDINGS_POOLING/EMBEDDINGS_NORMALIZENone覆盖仓库声明的池化/归一化仅对声明不了的仓库或刻意覆盖时设置EMBEDDINGS_DELEGATE_TO_WORKERtrue查询嵌入委托给 worker设EMBEDDINGS_BASE_URL时被忽略EMBEDDINGS_QUEUEembeddings嵌入任务路由队列显式-Q的 worker 必须列出EMBEDDINGS_DELEGATE_TIMEOUT60等待 worker 的秒数AZURE_EMBEDDINGS_DEPLOYMENT_NAMENoneAzure OpenAI 嵌入部署名核心结论嵌入配置的正确姿势取决于部署形态——轻量单机可全用默认本地模型 worker 委托多副本生产部署优先指向真正的嵌入服务EMBEDDINGS_BASE_URL从 API 与 worker 两侧移除模型而任何EMBEDDINGS_NAME的变更无论新旧模型维度是否相同都应以reembed --dry-run评估、reembed执行作为标准收尾动作。【免费下载链接】DocsGPTPrivate AI platform for agents, assistants and enterprise search. Built-in Agent Builder, Deep research, Document analysis, Multi-model support, and API connectivity for agents.项目地址: https://gitcode.com/GitHub_Trending/do/DocsGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考