实用笔记：介绍 Docling Pipeline：构建企业级 RAG 系统
《实用笔记》操作指南：了解 Docling Pipeline：构建企业级 RAG——为采用该模式的团队提供合同、检查项以及可直接插入的代码模块。
本指南将逐步构建从原材料到可运行系统的完整流程，内容来自《介绍 Docling Pipeline：构建企业级 RAG 数据管道》一书。重点在于可操作的步骤、明确的检查点，以及可直接放入代码仓库的代码，无需猜测其用途。
“胶水代码”的问题
在“胶水代码的问题”阶段，应在修改代码之前明确输入内容、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功标准，并拒绝默许部分完成的情况。 需注明实际作为答案依据的段落。如果没有引用，操作人员就无法区分是幻觉内容还是索引缺失导致的错误。
什么是 docling-pipelines？
在“什么是 docling-pipelines”阶段，应在修改代码之前明确输入内容、该步骤的负责人以及结束标准。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况可以避免在从演示环境过渡到共享环境时出现意外费用。必须注明实际作为答案依据的段落；如果没有引用，操作员就无法区分是幻觉内容还是索引缺失导致的错误。
bash
pip install docling-pipelines
核心思维模型：操作员与流程
在“核心思维模型”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作员无需查看整个系统结构即可进行审核。 当下一步是代码执行或工具调用时，优先使用具有架构验证的结构化输出，而非自由形式的文本描述。
from docpipe.core.operators.abstract_operator import AbstractOperator, OperatorCategory
import pyarrow as pa
class MyOperator(AbstractOperator):
short_name = "my_operator"
category = OperatorCategory.Quality
def __init__(self, config: dict) -> None:
super().__init__(config)
def transform(self, table: pa.Table) -> tuple[list[pa.Table], dict]:
metadata = self.create_base_metadata(total_docs_count=len(table))
# … process table …
return [table], metadata
@staticmethod
def get_metadata() -> dict:
return {"short_name": "my_operator", "description": "…"}
操作员生态系统概览
在为流程阶段进行设计时，应在修改代码之前明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 必须引用那些真正作为答案依据的段落。如果没有引用，操作人员就无法区分是虚假信息还是索引缺失导致的问题。
真实流程的样貌
在“真正的流程是怎样的”阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 相较于冗长的脚本，更应采用小型、可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。 需引用实际作为答案依据的段落。没有引用的话，操作人员就无法区分是虚假信息还是索引缺失导致的错误。 在“真正的流程是怎样的”阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境转向共享环境时出现意外费用。
{
"flow_name": "complete-document-pipeline",
"global_config": {
"doc_column": "content",
"storage": "in-memory"
},
"flow": [
{
"type": "ingest_source",
"name": "ingest_local_folder",
"config": {
"provider": "filesystem",
"connection_params": {
"paths": [
"./sample_documents"
]
},
"include_filter": "pdf,txt,docx"
}
},
{
"type": "extract_operator",
"name": "extract_with_docling",
"config": {
"text_extraction": {
"provider": "docling_library"
},
"entity_extraction": {
"provider": "none"
}
},
"depends_on": [
"ingest_local_folder"
]
},
{
"type": "chunker",
"name": "simple_chunker",
"config": {
"chunk_type": "simple",
"chunk_size": 512,
"chunk_overlap": 50
},
"depends_on": [
"extract_with_docling"
]
},
{
"type": "embeddings",
"name": "ollama_embeddings",
"config": {
"provider": "litellm",
"provider_config": {
"model_id": "openai/nomic-embed-text",
"api_base": "http://localhost:11434/v1"
},
"embeddings_column": "embeddings"
},
"depends_on": [
"simple_chunker"
]
},
{
"type": "vectordb",
"name": "opensearch_vector_store",
"config": {
"provider": "opensearch",
"doc_id_column": "doc_id_hash",
"embeddings_column": "embeddings",
"provider_config": {
"index_name": "sample-documents-index",
"host": "localhost",
"port": 9200
}
},
"depends_on": [
"ollama_embeddings"
]
}
]
}
docling-pipelines - flow-file pipeline.json
高级模式：分支处理、高质量路由与多阶段增强
在处理“高级模式：分支处理与高质量路由”阶段时，首先明确需求规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。
{
"name": "quality_branching",
"type": "branching",
"config": {
"branches": {
"high_quality_branch": {
"link_name": "High Quality Documents",
"criteria_json": {
"criteria_list": [
{
"variable": "flesch_reading_ease",
"operator": ">",
"value": 60
}
],
"logical_operator": "AND"
}
},
"low_quality_branch": {
"link_name": "Low Quality Documents",
"criteria_json": {
"criteria_list": [
{
"variable": "flesch_reading_ease",
"operator": "<=",
"value": 60
}
],
"logical_operator": "AND"
}
}
}
},
"depends_on": [
"readability"
]
}
lang_detect → ededup → doc_quality → readability → sql_filter → embeddings
{
"criteria_list": [
{
"variable": "docq_total_words",
"operator": ">",
"value": 100
},
{
"variable": "lang_name",
"operator": "=",
"value": "en"
}
],
"logical_operator": "AND"
}
三种运行方式
在完成“三种运行方式”阶段时，首先写下契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续的优化内容。 在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难解决检索效果不佳的问题。
docling-pipelines - flow-file pipeline.json
docling-pipelines - flow-file pipeline.json - validate # validate without running
docling-pipelines - list-operators - verbose # discover all registered operators
from docpipe.lib.docpipe_flow_manager import DocpipeFlowManager
manager = DocpipeFlowManager(flow_file="pipeline.json")
manager.execute()
uvicorn docpipe.api.main:app - host 0.0.0.0 - port 8000
使用自定义操作符进行扩展
在“使用自定义操作符进行扩展”阶段，首先需明确相关规范：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合预期。 相较于冗长的脚本，应优先选择小型且可测试的单元。当某一步骤失败时，故障应指向单一责任点，而非复杂的流程链。 在调整提示词之前，需先使用固定的问题集测试召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。 在“使用自定义操作符进行扩展”阶段，首先需明确相关规范：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合预期。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
DOCPIPE_CUSTOM_OPERATORS=./my_operators docling-pipelines - flow-file pipeline.json
内置的卓越运营能力
将“内置的卓越运营能力”阶段视为可度量的指标来使用效果最佳。在扩大范围之前，先收集一份优秀的操作记录、一个故障案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能标志应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 需将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制要求重新编写另一项。
Docling流水线系列
The Docling Pipelines Series 的各阶段在被视为可度量的对象时效果最佳。在扩大范围之前，先记录一个成功的处理案例、一个失败案例以及回滚说明。 同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。 将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。
下一步计划
“下一步计划”阶段若被视为可度量的工作面，效果会更好。在扩大范围之前，先记录一份最佳示例、一个故障案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤出现故障时，故障应指向单一责任点，而非复杂的流程链。 将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。 “下一步计划”阶段若被视为可度量的工作面，效果会更好。在扩大范围之前，先记录一份最佳示例、一个故障案例以及回滚说明。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
操作检查清单
将操作检查清单阶段视为可度量的标准，效果最佳。在扩大范围之前，先记录一份完美的测试用例、一个故障案例以及回滚说明。
把这一阶段视为输入与已验证输出之间的契约。为相关文档命名，明确成功标准，绝不允许出现悄无声息的半完成状态。
将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。
在预算允许的情况下，使用测试环境而非真实的付费 API，在持续集成过程中添加能够检测关键路径的冒烟测试。
在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。
应将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制重新编写另一项。
在升级该技术栈之前，先冻结版本，为关键路径生成标准转录文本，并明确回滚步骤。共享环境需要设置速率限制、租户检查机制，以及明确的密钥轮换负责人。与其追求花哨的一次性演示，不如注重扎实的可靠性。
d05b0d271243的批注：不要将提供商密钥放入代码仓库，为每个会话设置令牌上限，并将转录文本存储在评估用示例文件旁边，以便后续模型更换时仍能保持可比性。
在处理强化措施的第0阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合约定。 将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝默许的部分完成情况。
强化措施细节0/754：需测量该环节的运行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
将强化措施的第1阶段视为可量化的目标面来处理效果最佳。在扩大范围之前，先记录一份理想的运行日志、一个失败案例以及回滚说明。 应将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一处，以便操作人员无需查看全部代码结构即可进行审计。
强化措施细节1/754：记录该任务的执行时间、错误类型以及代币消耗情况，然后依据固定的问题清单而非个人经验来判断是否保留该变更。
在强化措施的第二阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比复杂的脚本，更应采用小型且可测试的单元。当某一步骤失败时，故障原因应能指向具体的责任主体，而非混乱的整个流程。
强化措施细节2/754：记录该任务的执行时间、错误类型以及代币消耗情况，然后依据固定的问题清单而非个人经验来判断是否保留该变更。
在处理强化措施的第3阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合初始要求。
在功能结果旁记录执行时间以及令牌或查询成本。提前了解这些成本信息，可避免在系统从演示环境过渡到共享环境时出现意外费用。
强化措施细节3/754：需测量该步骤的耗时、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该修改。
将强化措施的第4阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一个理想运行案例、一个失败案例以及回滚说明。
应同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续需要补充的内容。
强化措施细节4/754：记录该任务的执行时间、错误类型以及代币消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
在强化措施的第5阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应将此阶段视为输入参数与验证后输出结果之间的契约，为相关成果命名、定义成功判定条件，并拒绝默许部分完成的情况。
强化措施细节5/754：记录该任务的执行时间、错误类型以及代币消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
在处理强化措施的第6阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。 应将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。
强化措施细节6/754：需测量该措施的执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该修改。
将强化措施的第7阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的运行日志、一个失败案例以及回滚说明。 相比复杂的脚本，更应采用小型且可测试的单元。当某个步骤出现故障时，故障原因应能明确指向某个具体的责任模块，而非整个复杂的流程。
强化措施细节 7/754：为该记录测量运行时间、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在强化措施的第8阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录时间以及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
强化措施细节 8/754：为该记录测量运行时间、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在处理强化措施的第9阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。
同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续才添加的完善措施。
强化措施细节9/754：需测量该阶段的执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
将强化措施的第10阶段视为一个可量化的目标面，效果最佳。在扩大范围之前，先记录一份理想的操作日志、一个故障案例以及回滚说明。
要把这一阶段视为输入参数与验证后输出结果之间的契约。为相关文档命名，明确成功判定标准，杜绝无声的半完成状态。
强化措施细节 10/754：记录该条注解的运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
对于强化措施的第11阶段，在修改代码之前需明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。配置应置于应用程序代码之外，环境文件、密钥存储以及功能标志应集中存放于一个操作人员可以审核的位置，无需查看整个系统结构。
强化措施细节 11/754：记录该条注解的运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在处理强化措施的第12阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。 相比冗长的脚本，更应选择小型且可测试的单元。当某个步骤失败时，故障应能指向单一的责任模块，而非复杂的流程链。
强化措施细节12/754：需测量该步骤的运行时间、错误类型以及代币消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该修改。
将强化措施的第13阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的运行示例、一个失败案例以及回滚说明。 在功能结果旁同时记录时间消耗及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外支出。
强化措施细节13/754：测量该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在强化措施笔记的第14阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续的优化工作。
强化措施细节14/754：测量该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。