★ FEATURED ARTICLE Langchain-Chatchat 知识库模型解析DocumentWithVSId 向量化文档对象的字段、调用链与实战用法【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-ChatchatDocumentWithVSId是 Langchain-Chatchat 知识库RAG体系中最核心的数据载体之一它定义了经过向量化检索后返回给上层链路的文档的标准结构在 Langchain 原生Document的基础上扩展出id与score两个字段。本篇文章以 kb_document_model.md 文档为骨架结合 模型定义源码、知识库服务层、文档 API、文档摘要与 Agent 工具注册等真实实现系统讲解它的类结构、字段语义、三条典型调用链搜索、列举、摘要以及在参数调优与二次开发时的注意事项。读完本文你将能准确理解向量检索结果中的id与score从哪来、代表什么、如何被消费并能据此正确使用search_docs/list_docs相关接口或在自定义知识库后端中复用它。一、类定位RAG 链路中检索结果的统一封装在 Langchain-Chatchat 的知识库问答RAG流程中一条完整的数据流大致是用户提问 → 文本向量化 → 在向量库Faiss / Milvus / Chroma / ES / PG 等中做相似度检索 →得到若干向量化后的文档→ 拼装进 Prompt 交给大模型回答或用于知识库文件管理、文档摘要等功能模块。这一环节的返回结果对象正是DocumentWithVSId。正如文档中描述的那样它继承自Document类用于表示一个经过向量化处理的文档在知识库系统中承担检索结果 / 处理结果的统一表示职责。模型定义文件位于 kb_document_model.py完整实现十分精简from langchain.docstore.document import Document class DocumentWithVSId(Document): 矢量化后的文档 id: str None score: float 3.0可以看到它利用 Pydantic 模型继承机制在 Langchain 的Document基础上只新增了两个字段id字符串默认None与score浮点数默认3.0。底层Document本身自带的page_content文档正文与metadata元数据字典两个字段会被原样继承因此一个完整的DocumentWithVSId实例实际承载的信息包括正文内容、元数据、向量库中的唯一标识id、与查询的相关性评分score四部分。二、字段语义id 与 score 分别表示什么结合 原文档 与源码实现两个扩展字段的语义如下字段类型默认值语义说明idstrNone文档在知识库 / 向量库中的唯一标识符。文档指出需保证其唯一性确保每个实例能够准确对应知识库中的一个具体文档实践中它常与向量索引中的 doc_id如 Faiss 缓存中的文档 ID、metadata中的id保持一致scorefloat3.0文档与检索查询的匹配度 / 相关性度量会在搜索、排序等操作中被更新。文档特别提醒取值可能随操作或上下文环境变化使用时应注意其含义与计算方式关于score的方向需要结合 Langchain-Chatchat 的检索实现来理解。在 kb_chat.py 的接口参数注释中明确写道知识库匹配相关度阈值取值范围在 0-1 之间SCORE越小相关度越高取到 1 相当于不筛选建议设置在 0.5 左右因此在本项目中score本质是一种距离 / 不相似度度量而非百分制相似度数值越小表示与查询越相关默认值3.0处于不设限的量级——即当一个文档实例未经检索打分、只做结构化包装时例如在按file_name/metadata列举文档的场景下它不会被误判为高度相关。默认值3.0还有一个直接意义任何通过DocumentWithVSId(id..., score3.0)形式构造的对象在未进入打分流程前都带有这个中性评分避免后续逻辑对未打分文档做无效的阈值截断。三、构造方式两种核心初始化模式从源码看DocumentWithVSId的实例化在整个代码库中遵循两种模式它们都出现在知识库 API 与摘要链路中模式一由底层Document展开后补齐id在 kb_doc_api.py 中搜索结果的包装逻辑为data [DocumentWithVSId(**{id: x.metadata.get(id), **x.dict()}) for x in docs]即在保留page_content、metadata等字段的同时从文档元数据的id键中提取唯一标识注入id字段该文件同位置还保留了一行注释掉的旧写法DocumentWithVSId(**x[0].dict(), scorex[1], ...)从侧面印证了score在部分向量库检索实现中作为二元组第二项返回的历史形态。模式二dict()展开后叠加外部id在文档摘要接口 kb_summary_api.py 中doc_info_with_ids [ DocumentWithVSId(**{**doc.dict(), id: with_id}) for with_id, doc in zip(doc_ids, doc_infos) ]将待摘要的文档 ID 列表与按 ID 取回的文档内容列表一一配对生成带 ID 的摘要输入。这里的with_id来自知识库服务层的kb.get_doc_by_ids(idsdoc_ids)是各向量库后端实现中真正存储的文档 ID。此外在知识库服务基类 kb_service/base.py 的list_docs中同样采用DocumentWithVSId(**{**doc_info.dict(), id: x[id]})的形式完成包装。四、三种核心使用场景与底层调用链原文档归纳了DocumentWithVSId的三个主要应用场景下面逐一对应到仓库源码中的真实调用链。场景一知识库文档搜索search_docs当调用知识库文档搜索接口时入口位于 kb_doc_api.py 的search_docs通过KBServiceFactory.get_service_by_name(knowledge_base_name)取得当前知识库的服务实例Faiss / Milvus / Chroma / ES / PG 等具体实现有查询词query时调用kb.search_docs(query, top_k, score_threshold)服务基类的 search_docs 实现 会先校验 Embedding 模型可用性再委托给各后端实现的do_search(query, top_k, score_threshold)完成真正的相似度检索返回的每个文档经DocumentWithVSId包装后通过 HTTP JSON 序列化[x.dict() for x in data]返回给调用方。此处top_k与score_threshold的默认值分别来自配置项Settings.kb_settings.VECTOR_SEARCH_TOP_K与Settings.kb_settings.SCORE_THRESHOLD。这两个参数会直接影响返回的DocumentWithVSId数量与评分分布——在服务层检索时低于score_threshold即相似度过低 / 距离过大的结果会被过滤掉。该接口也被知识库对话直接复用在 kb_chat.py 的知识库问答流程中同样会以query、top_k、score_threshold等参数触发上面的搜索链路随后将检索出的文档交给format_reference格式化作为引用出处一并呈现在回答中。场景二按文件名 / 元数据列举与过滤文档list_docs当知识库文件管理界面需要按文件名或元数据列出文档内容时会走 kb_service/base.py 的 list_docs先从数据库仓库层list_docs_from_db(kb_name, file_name, metadata)查出符合条件支持文件名与一级键元数据过滤的文档信息列表doc_infos对每个x通过get_doc_by_ids([x[id]])[0]从向量库按 ID 取回真实文档内容非空时包装为DocumentWithVSId(**{**doc_info.dict(), id: x[id]})加入结果列表为空时跳过该条源码中的pass分支。对应的 HTTP 入口同样是 kb_doc_api.py当请求只携带file_name或metadata而不携带query时触发。值得注意的一个实现细节是为降低响应体积该路径返回前会执行del d.metadata[vector]从元数据中剔除向量字段后再序列化输出。在该场景下返回的文档实例score保持默认的3.0因为并未发生真正的相似度计算这也再次验证了原文档score 会随操作环境变化的说明。场景三文档摘要KBSummary中的输入载体DocumentWithVSId也是知识库文档摘要功能的输入格式。调用链位于 kb_summary_api.py 的recreate_summary_vector_store/summary_doc_ids_to_vector_store系列接口通过kb.get_doc_by_ids(idsdoc_ids)按 ID 批量取回待摘要文档如前述模式二构造出doc_info_with_ids即一串DocumentWithVSId交给 summary_chunk.py 中的SummaryAdapter内部使用MapReduceDocumentsChain做分块-合并式摘要的summarize(file_description..., docsdoc_info_with_ids)生成摘要摘要结果随后按原文档 ID 回写知识库摘要存储从而支持后续的摘要级检索与引用。在这里id承担的是把摘要结果与原始文档关联回写的关键职责缺失或错乱的id将直接导致摘要与原文无法对应。五、在 Agent 工具与 WebUI 中的进一步消费除了知识库服务层DocumentWithVSId还被更高层的 Agent 与前端界面所消费Agent 工具上下文组装在 tools_registry.py 的format_context中Agent 搜索知识库得到的结果集docs会逐条执行DocumentWithVSId.parse_obj(doc)反序列化再抽取doc.page_content拼装为给大模型的上下文文本若结果为空则生成没有找到相关文档请更换关键词重试的提示语。这说明DocumentWithVSId不仅存活在服务端内部还会以 JSON 形态跨进程传输后被再次解析。WebUI 对话页在 dialogue.py 中该模型类被导入用于对知识库引用文档做类型化处理与format_reference配合渲染答案下方的引用出处。从导入关系看WebUI 直接引用的是chatchat.server.knowledge_base.model.kb_document_model即本模型文件中的类而 Agent 侧则经由kb_doc_api间接导入。由此可见从向量库检索结果到对话引用展示再到Agent 工具返回DocumentWithVSId是整个知识库召回结果的标准数据契约。六、源码结构上的设计说明与注意事项最后结合源码与文档的注意提示归纳几条对二次开发最有价值的设计要点极轻量的继承扩展模型文件本身只有 3 个有效代码行设计上刻意不复制 LangchainDocument的字段而是依靠 Pydantic 继承自动获得page_content、metadata等能力。任何知识库后端只要返回标准Document 额外 ID即可无损转换为DocumentWithVSId。id的唯一性约定id默认None但按文档要求它应当与知识库 / 向量库中的某个具体文档一一对应。在 Faiss 等本地缓存实现与数据库记录之间正是靠这个id完成文件—分块—向量—摘要的多层关联因此不要随意置空或复用。score的语义随场景漂移检索场景下它是越小越相关的距离型度量并受SCORE_THRESHOLD默认由 kb_settings 配置影响列举场景下它保持默认值3.0不参与任何过滤。消费端切勿假设score 高即相关。直接可用的序列化能力由于继承自 Pydantic 模型DocumentWithVSId天然支持dict()源码中多次使用、parse_obj()Agent 工具侧使用与 JSON 序列化跨进程、跨模块传递非常方便这解释了为何它能在 API 返回体与 WebUI 中自由流动。扩展自定义字段的落点如需要给检索结果附加更多信息如来源文件、页码、块序号等惯例是写入继承自Document的metadata字典而不是修改模型类的字段集——项目各 API 均已按此约定从metadata读取或剔除如id从metadata[id]提取、vector从metadata中删除。七、小结DocumentWithVSId虽然是一个仅含两个新增字段的轻量数据类却是 Langchain-Chatchat 知识库 RAG 链路承上启下的关键协议Document负责承载内容与元数据id负责打通数据库记录 ↔ 向量库索引 ↔ 摘要结果的映射关系score则承载检索相关性信息并贯穿VECTOR_SEARCH_TOP_K、SCORE_THRESHOLD等调优参数。无论是阅读 搜索文档 API、编写自定义知识库后端还是二次开发 Agent 知识库工具理解这一模型类的字段语义与三条构造 / 消费路径都是绕不开的第一步。【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
