Docling 文档转换实战从技术架构指南 PDF 到结构化 Markdown 与 RAG 数据流水线【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agentsDocling 是一套开箱即用的文档处理库能够将 PDF、Word、PowerPoint、Excel、HTML 乃至音频文件统一转换为结构完整、RAG 友好的 Markdown。本文以仓库中的样例文档 documents/technical-architecture-guide.pdf 为对象完整展示 Docling 的转换输出即 docling_basics/output/output_technical-architecture-guide.md并顺着 docling-rag-agent 项目的源码脉络讲解从文档解析、混合分块、向量化入库到 RAG 问答的完整数据流水线。读完本文你将掌握 Docling 处理复杂版式文档的原理、输出内容的价值评估以及如何在生产级 RAG 系统中复现这一流程。一、样本文档背景这份 PDF 里有什么technical-architecture-guide.pdf是 docling-rag-agent 项目documents/目录下的样例文档内容是一份企业级 AI 平台的架构指南内部工程团队文档。它的特殊之处在于包含了多级标题层级、代码块、大量参数表格、嵌套流程图文本等对文本抽取极具挑战性的元素——这正是传统 PDF 解析器最容易丢失信息的地方。Docling 把这份 PDF 转换成了结构完整的 output_technical-architecture-guide.md保留了从## 1. System Overview到## 11. API Endpoints Reference的全部章节结构。这份输出文件既是 Docling 能力的直观证明也是后续 RAG 检索可用的高质量语料。二、一键转换Docling 最简用法仓库中的 01_simple_pdf.py 演示了 Docling 的最基本用法核心代码只有三行from docling.document_converter import DocumentConverter converter DocumentConverter() # 初始化转换器 result converter.convert(pdf_path) # 转换 PDF markdown result.document.export_to_markdown() # 导出为 Markdown运行方式python 01_simple_pdf.py脚本会把转换结果写入output/output_simple.md并在控制台打印前 1000 个字符预览。无需任何配置Docling 就能自动完成版式分析、表格识别、多栏布局还原——这也是 docling_basics/README.md 中强调的开箱即用不需要自定义 OCR、不需要为每种格式单独写解析器。三、转换输出深度解析一份企业架构指南的完整还原以下内容全部来自 Docling 对technical-architecture-guide.pdf的转换结果读者可以对照 output_technical-architecture-guide.md 逐节核对。3.1 系统概览与架构原则文档开篇定义了一个名为 NeuralFlow AI Platform v2.0 的云原生 AI 自动化系统转换后的 Markdown 保留了版本号v2.0、文档版本2.3、更新日期December 15, 2024等元信息并完整还原了五项架构原则微服务化支持独立扩缩容与部署事件驱动通信实现松耦合多租户架构带数据隔离云无关设计提供 Provider 抽象全服务 API-first 设计值得注意的是转换结果中标题层级## 3.1 API Gateway这类三级标题被精确保留说明 Docling 对嵌套标题结构的识别是可靠的——这对于后续依赖标题层级做语义分块至关重要。3.2 核心组件第三章转换输出完整保留了四个核心组件的说明API 网关3.1作为所有客户端请求的唯一入口负责认证、限流、请求校验与路由。转换输出保留了一段 YAML 风格配置示例gateway: host: api.neuralflow-ai.com port: 443 ssl: true rate_limit: requests_per_minute: 1000 burst: 100 auth: type: jwt token_expiry: 3600 routes: - path: /v1/documents/* service: document-processor methods: [POST, GET] - path: /v1/chat/* service: conversational-ai methods: [POST, GET, DELETE]这段代码块在 PDF 中是以多行代码形式存在的Docling 将其还原为可读的 YAML 结构并保留在代码块中说明其具备代码块识别能力对应 docling_basics/README.md 中提到的 Code Understanding 增强特性。文档处理服务3.2负责文档智能摄入、OCR、抽取、分类与分析。转换输出保留了一张技术选型表组件技术用途文档解析器PyPDF2、python-docx、Pillow从文档中抽取文本与元数据OCR 引擎Tesseract、AWS Textract图像的光学字符识别实体抽取spaCy、自定义 NER 模型识别关键实体与关系分类微调 BERT、GPT-4文档类型归类数据校验自定义规则引擎校验抽取数据准确性对话式 AI 服务3.3支持聊天机器人与虚拟助手提供自然语言理解、上下文管理与多轮对话能力并特别强调了合规要求内容过滤、PII 检测、对话日志。RAG 系统3.4这是与当前仓库关联最紧密的章节。转换输出保留了一段完整的 RAG 管线架构描述1. 文档摄入Document Ingestion └─ 分块500-1000 tokens └─ 嵌入生成text-embedding-ada-002 └─ 向量存储Pinecone/Weaviate 2. 查询处理Query Processing └─ 查询嵌入 └─ 语义搜索k5-10 └─ 重排序Cohere Rerank └─ 上下文组装 3. 生成Generation └─ Prompt 构造 └─ LLM 推理GPT-4、Claude └─ 响应校验 └─ 引文生成这段流程图文本以字符画形式呈现Docling 将其作为文本块完整保留没有破坏其层级缩进——这正是文档结构保真的体现。3.3 技术栈与数据流第四、五章转换输出保留了 BackendPython 3.11 / FastAPI / Celery、FrontendReact 18 / TypeScript / Next.js 14、DatabasePostgreSQL 15 / Redis 7 / MongoDB三组技术栈信息并还原了文档处理流程的步骤表步骤动作输出平均耗时1文档上传S3 URL、Job ID200ms2格式检测文档类型50ms3文本抽取原始文本、元数据2-5s4OCR如需识别文本5-15s5实体抽取结构化数据1-3s6分类文档类别500ms7校验置信度分数300ms8存储数据库记录100ms3.4 安全架构第六章转换输出完整保留了六层安全机制表层机制实现网络VPC 隔离私有子网、NAT 网关、安全组应用认证JWT、OAuth 2.0、SSO 集成数据加密AES-256 静态加密、TLS 1.3 传输加密访问控制RBAC细粒度权限、角色层级监控审计日志不可变日志、SIEM 集成合规数据驻留区域化部署、数据主权以及 API 认证时序POST /v1/auth/login→ 凭据校验bcrypt 哈希、查用户库→ 令牌生成JWT payload、RSA 私钥签名、1 小时过期→ 返回access_token、refresh_token、expires_in。3.5 性能优化、监控与容灾第七九章缓存策略表被完整还原缓存类型使用场景TTL失效方式Redis 热数据高频查询、会话数据5-60 分钟事件驱动CDN 静态资源图片、JS、CSS24 小时版本驱动应用缓存配置、特性开关15 分钟时间驱动数据库查询缓存昂贵读查询5 分钟写失效监控章节列出了黄金信号延迟、流量、错误、饱和度、业务指标与基础设施指标三类度量。备份策略表则给出了数据库持续备份、30 天保留、RTO1h、RPO5min、文档存储每日备份、90 天保留、配置变更时备份、无限期保留与模型产物部署时备份、全版本保留四类数据的不同 SLA。3.6 部署管线与 API 端点第十、十一章CI/CD 管线以文本流程图形式保留代码提交触发 webhook → 构建flake8/black 检查、pytest 单测、构建 Docker 镜像、推送镜像仓库→ 测试集成测试、Snyk 安全扫描、性能测试→ 预发部署冒烟测试、人工审批门禁→ 生产部署5% 流量金丝雀、15 分钟指标监控、25%→50%→100% 渐进放量、异常自动回滚。API 端点参考表也完整保留端点方法用途是否需要认证/v1/documents/uploadPOST上传文档进行处理是/v1/documents/{id}GET获取文档结果是/v1/chat/conversationPOST开启新对话是/v1/chat/messagePOST在对话中发送消息是/v1/analytics/queryPOST运行分析查询是/v1/healthGET系统健康检查否四、为什么 Docling 能保住这些复杂结构上面的转换输出之所以完整是因为 Docling 的解析管线做了三件关键事情参见 docling_basics/README.md版式分析与 OCR 兜底内置 OCR 能力EasyOCR 支持扫描件也能抽取文字无需另写 OCR 服务表格结构识别通过 TableFormer 等模型识别复杂表格、跨页表格与单元格关系因此第三、五、六、七、九、十一章的表格才能以 Markdown 表格形式还原层级与元数据保留标题层级、段落、代码块被映射为 DoclingDocument 的内部结构导出 Markdown 时按语义层级输出。仓库中的 02_multiple_formats.py 进一步证明同一套DocumentConverterAPI 可以处理 PDF、Word、Markdown 等多种格式只需初始化一次转换器即可批量处理并输出统一的 Markdown 结果与转换摘要。这解释了为何 ingestion/ingest.py 的_read_document()方法能够用一份代码同时覆盖.pdf/.docx/.pptx/.xlsx/.html等多种格式。五、从转换到 RAG仓库里的完整落地Docling 输出的高质量 Markdown 只是第一步docling-rag-agent 展示了如何把它接入生产级 RAG 流水线。整条链路是Docling 转换 → HybridChunker 分块 → OpenAI 嵌入 → PGVector 存储 → 语义检索 → LLM 生成。5.1 摄入管线ingest.pyingestion/ingest.py 的_read_document()按扩展名分流音频文件走 Whisper ASR 转录返回纯文本Docling 支持格式走DocumentConverter转换为 Markdown 并同时返回 DoclingDocument 对象供混合分块复用避免二次解析纯文本格式直接读取。转换失败时还有兜底逻辑回退到原始文本读取保证管线健壮性。摄入命令uv run python -m ingestion.ingest --documents documents/ # 默认 chunk-size 1000 uv run python -m ingestion.ingest --documents documents/ --chunk-size 800注意默认行为每次摄入前会清空数据库中的 documents 和 chunks 表--no-clean可跳过确保无重复数据。5.2 混合分块chunker.pyingestion/chunker.py 封装了 Docling 的HybridChunkerself.chunker HybridChunker( tokenizerself.tokenizer, # sentence-transformers/all-MiniLM-L6-v2 max_tokensconfig.max_tokens, # 默认 512适配嵌入模型上限 merge_peersTrue # 合并过小的相邻块 )核心思路是结构感知 词元精确块边界尊重段落、章节、表格等语义边界而不是机械地按字符数切割contextualize()会把标题层级heading hierarchy注入每个块保证块脱离原文档后仍具备上下文。这也对应教程脚本 04_hybrid_chunking.py 演示的内容——它以 512 token 为上限对technical-architecture-guide.pdf分块输出块数、总 token 数、均值/极值及 token 分布统计并保存带上下文的分块结果到output/output_chunks.txt。如果 DoclingDocument 不可用或分块失败chunker.py还内置了滑动窗口兜底分块按句号/换行找边界与段落式 SimpleChunker可通过use_semantic_splitting配置切换。5.3 嵌入与存储embedder.py schema.sqlingestion/embedder.py 默认使用text-embedding-3-small1536 维支持批量嵌入batch_size100、限流指数退避重试、超长文本截断并带一个简单的 LRU 风格内存缓存EmbeddingCache减少重复 API 调用。数据库侧由 sql/schema.sql 定义documents表存原始文档与元数据chunks表存文本块、vector(1536)嵌入向量、chunk_index与token_count并建立ivfflat (vector_cosine_ops)向量索引。核心查询函数match_chunks()用余弦距离计算相似度SELECT c.id, c.document_id, c.content, 1 - (c.embedding query_embedding) AS similarity, d.title AS document_title, d.source AS document_source FROM chunks c JOIN documents d ON c.document_id d.id WHERE c.embedding IS NOT NULL ORDER BY c.embedding query_embedding LIMIT match_count;5.4 检索问答rag_agent.pyrag_agent.py 用 PydanticAI 定义了一个注册了search_knowledge_base工具的 Agent查询先经embed_query()生成嵌入再调用match_chunks()取 top-k 相关块默认 5结果带来源标题格式化后交给 LLM 生成带引文的回答交互层使用run_stream逐 token 流式输出。启动命令uv run python cli.pyCLI 提供help、clear、stats、exit/quit等命令启动时会做数据库健康检查。六、进阶能力与调优方向除了基础转换docling_basics/README.md 还记录了三个可选增强点图片描述pipeline_options.do_picture_description True并配置granite_picture_description用 IBM Granite Vision 自动生成图片/图表说明让视觉内容也可被检索代码理解do_code_enrichment True保留语法高亮、代码块识别与语言检测适合处理含代码的技术文档本文样例正是此类文档表格结构识别table_structure_options.mode TableFormerMode.ACCURATE提升复杂/跨页表格的抽取精度。音频场景则由 03_audio_transcription.py 演示通过AsrPipelineOptionsasr_model_specs.WHISPER_TURBO配置 Docling 的 ASR 管线把 MP3/WAV/M4A/FLAC 转录为带[time: 0.0-4.0]时间戳标记的 Markdown需要系统安装 FFmpeg使播客、访谈等音频内容同样可进入 RAG 知识库。七、小结以technical-architecture-guide.pdf为样本可以看出Docling 的价值在于把转换从信息丢失的瓶颈变成 RAG 质量的第一道保障——它既保住了表格、代码块、层级标题这些传统解析器最容易丢的结构又通过 HybridChunker 让分块天然适配嵌入模型的 token 限制。而 docling-rag-agent 仓库则给出了从这第一步到最后问答的完整参考实现docling_basics/四个渐进式教程负责理解能力边界ingestion/三件套ingest.py、chunker.py、embedder.py负责工程落地schema.sql 与 rag_agent.py 负责检索与问答闭环。遇到复杂版式文档的 RAG 场景这条路径可以直接复用。【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Docling 文档转换实战：从技术架构指南 PDF 到结构化 Markdown 与 RAG 数据流水线
Docling 文档转换实战从技术架构指南 PDF 到结构化 Markdown 与 RAG 数据流水线【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agentsDocling 是一套开箱即用的文档处理库能够将 PDF、Word、PowerPoint、Excel、HTML 乃至音频文件统一转换为结构完整、RAG 友好的 Markdown。本文以仓库中的样例文档 documents/technical-architecture-guide.pdf 为对象完整展示 Docling 的转换输出即 docling_basics/output/output_technical-architecture-guide.md并顺着 docling-rag-agent 项目的源码脉络讲解从文档解析、混合分块、向量化入库到 RAG 问答的完整数据流水线。读完本文你将掌握 Docling 处理复杂版式文档的原理、输出内容的价值评估以及如何在生产级 RAG 系统中复现这一流程。一、样本文档背景这份 PDF 里有什么technical-architecture-guide.pdf是 docling-rag-agent 项目documents/目录下的样例文档内容是一份企业级 AI 平台的架构指南内部工程团队文档。它的特殊之处在于包含了多级标题层级、代码块、大量参数表格、嵌套流程图文本等对文本抽取极具挑战性的元素——这正是传统 PDF 解析器最容易丢失信息的地方。Docling 把这份 PDF 转换成了结构完整的 output_technical-architecture-guide.md保留了从## 1. System Overview到## 11. API Endpoints Reference的全部章节结构。这份输出文件既是 Docling 能力的直观证明也是后续 RAG 检索可用的高质量语料。二、一键转换Docling 最简用法仓库中的 01_simple_pdf.py 演示了 Docling 的最基本用法核心代码只有三行from docling.document_converter import DocumentConverter converter DocumentConverter() # 初始化转换器 result converter.convert(pdf_path) # 转换 PDF markdown result.document.export_to_markdown() # 导出为 Markdown运行方式python 01_simple_pdf.py脚本会把转换结果写入output/output_simple.md并在控制台打印前 1000 个字符预览。无需任何配置Docling 就能自动完成版式分析、表格识别、多栏布局还原——这也是 docling_basics/README.md 中强调的开箱即用不需要自定义 OCR、不需要为每种格式单独写解析器。三、转换输出深度解析一份企业架构指南的完整还原以下内容全部来自 Docling 对technical-architecture-guide.pdf的转换结果读者可以对照 output_technical-architecture-guide.md 逐节核对。3.1 系统概览与架构原则文档开篇定义了一个名为 NeuralFlow AI Platform v2.0 的云原生 AI 自动化系统转换后的 Markdown 保留了版本号v2.0、文档版本2.3、更新日期December 15, 2024等元信息并完整还原了五项架构原则微服务化支持独立扩缩容与部署事件驱动通信实现松耦合多租户架构带数据隔离云无关设计提供 Provider 抽象全服务 API-first 设计值得注意的是转换结果中标题层级## 3.1 API Gateway这类三级标题被精确保留说明 Docling 对嵌套标题结构的识别是可靠的——这对于后续依赖标题层级做语义分块至关重要。3.2 核心组件第三章转换输出完整保留了四个核心组件的说明API 网关3.1作为所有客户端请求的唯一入口负责认证、限流、请求校验与路由。转换输出保留了一段 YAML 风格配置示例gateway: host: api.neuralflow-ai.com port: 443 ssl: true rate_limit: requests_per_minute: 1000 burst: 100 auth: type: jwt token_expiry: 3600 routes: - path: /v1/documents/* service: document-processor methods: [POST, GET] - path: /v1/chat/* service: conversational-ai methods: [POST, GET, DELETE]这段代码块在 PDF 中是以多行代码形式存在的Docling 将其还原为可读的 YAML 结构并保留在代码块中说明其具备代码块识别能力对应 docling_basics/README.md 中提到的 Code Understanding 增强特性。文档处理服务3.2负责文档智能摄入、OCR、抽取、分类与分析。转换输出保留了一张技术选型表组件技术用途文档解析器PyPDF2、python-docx、Pillow从文档中抽取文本与元数据OCR 引擎Tesseract、AWS Textract图像的光学字符识别实体抽取spaCy、自定义 NER 模型识别关键实体与关系分类微调 BERT、GPT-4文档类型归类数据校验自定义规则引擎校验抽取数据准确性对话式 AI 服务3.3支持聊天机器人与虚拟助手提供自然语言理解、上下文管理与多轮对话能力并特别强调了合规要求内容过滤、PII 检测、对话日志。RAG 系统3.4这是与当前仓库关联最紧密的章节。转换输出保留了一段完整的 RAG 管线架构描述1. 文档摄入Document Ingestion └─ 分块500-1000 tokens └─ 嵌入生成text-embedding-ada-002 └─ 向量存储Pinecone/Weaviate 2. 查询处理Query Processing └─ 查询嵌入 └─ 语义搜索k5-10 └─ 重排序Cohere Rerank └─ 上下文组装 3. 生成Generation └─ Prompt 构造 └─ LLM 推理GPT-4、Claude └─ 响应校验 └─ 引文生成这段流程图文本以字符画形式呈现Docling 将其作为文本块完整保留没有破坏其层级缩进——这正是文档结构保真的体现。3.3 技术栈与数据流第四、五章转换输出保留了 BackendPython 3.11 / FastAPI / Celery、FrontendReact 18 / TypeScript / Next.js 14、DatabasePostgreSQL 15 / Redis 7 / MongoDB三组技术栈信息并还原了文档处理流程的步骤表步骤动作输出平均耗时1文档上传S3 URL、Job ID200ms2格式检测文档类型50ms3文本抽取原始文本、元数据2-5s4OCR如需识别文本5-15s5实体抽取结构化数据1-3s6分类文档类别500ms7校验置信度分数300ms8存储数据库记录100ms3.4 安全架构第六章转换输出完整保留了六层安全机制表层机制实现网络VPC 隔离私有子网、NAT 网关、安全组应用认证JWT、OAuth 2.0、SSO 集成数据加密AES-256 静态加密、TLS 1.3 传输加密访问控制RBAC细粒度权限、角色层级监控审计日志不可变日志、SIEM 集成合规数据驻留区域化部署、数据主权以及 API 认证时序POST /v1/auth/login→ 凭据校验bcrypt 哈希、查用户库→ 令牌生成JWT payload、RSA 私钥签名、1 小时过期→ 返回access_token、refresh_token、expires_in。3.5 性能优化、监控与容灾第七九章缓存策略表被完整还原缓存类型使用场景TTL失效方式Redis 热数据高频查询、会话数据5-60 分钟事件驱动CDN 静态资源图片、JS、CSS24 小时版本驱动应用缓存配置、特性开关15 分钟时间驱动数据库查询缓存昂贵读查询5 分钟写失效监控章节列出了黄金信号延迟、流量、错误、饱和度、业务指标与基础设施指标三类度量。备份策略表则给出了数据库持续备份、30 天保留、RTO1h、RPO5min、文档存储每日备份、90 天保留、配置变更时备份、无限期保留与模型产物部署时备份、全版本保留四类数据的不同 SLA。3.6 部署管线与 API 端点第十、十一章CI/CD 管线以文本流程图形式保留代码提交触发 webhook → 构建flake8/black 检查、pytest 单测、构建 Docker 镜像、推送镜像仓库→ 测试集成测试、Snyk 安全扫描、性能测试→ 预发部署冒烟测试、人工审批门禁→ 生产部署5% 流量金丝雀、15 分钟指标监控、25%→50%→100% 渐进放量、异常自动回滚。API 端点参考表也完整保留端点方法用途是否需要认证/v1/documents/uploadPOST上传文档进行处理是/v1/documents/{id}GET获取文档结果是/v1/chat/conversationPOST开启新对话是/v1/chat/messagePOST在对话中发送消息是/v1/analytics/queryPOST运行分析查询是/v1/healthGET系统健康检查否四、为什么 Docling 能保住这些复杂结构上面的转换输出之所以完整是因为 Docling 的解析管线做了三件关键事情参见 docling_basics/README.md版式分析与 OCR 兜底内置 OCR 能力EasyOCR 支持扫描件也能抽取文字无需另写 OCR 服务表格结构识别通过 TableFormer 等模型识别复杂表格、跨页表格与单元格关系因此第三、五、六、七、九、十一章的表格才能以 Markdown 表格形式还原层级与元数据保留标题层级、段落、代码块被映射为 DoclingDocument 的内部结构导出 Markdown 时按语义层级输出。仓库中的 02_multiple_formats.py 进一步证明同一套DocumentConverterAPI 可以处理 PDF、Word、Markdown 等多种格式只需初始化一次转换器即可批量处理并输出统一的 Markdown 结果与转换摘要。这解释了为何 ingestion/ingest.py 的_read_document()方法能够用一份代码同时覆盖.pdf/.docx/.pptx/.xlsx/.html等多种格式。五、从转换到 RAG仓库里的完整落地Docling 输出的高质量 Markdown 只是第一步docling-rag-agent 展示了如何把它接入生产级 RAG 流水线。整条链路是Docling 转换 → HybridChunker 分块 → OpenAI 嵌入 → PGVector 存储 → 语义检索 → LLM 生成。5.1 摄入管线ingest.pyingestion/ingest.py 的_read_document()按扩展名分流音频文件走 Whisper ASR 转录返回纯文本Docling 支持格式走DocumentConverter转换为 Markdown 并同时返回 DoclingDocument 对象供混合分块复用避免二次解析纯文本格式直接读取。转换失败时还有兜底逻辑回退到原始文本读取保证管线健壮性。摄入命令uv run python -m ingestion.ingest --documents documents/ # 默认 chunk-size 1000 uv run python -m ingestion.ingest --documents documents/ --chunk-size 800注意默认行为每次摄入前会清空数据库中的 documents 和 chunks 表--no-clean可跳过确保无重复数据。5.2 混合分块chunker.pyingestion/chunker.py 封装了 Docling 的HybridChunkerself.chunker HybridChunker( tokenizerself.tokenizer, # sentence-transformers/all-MiniLM-L6-v2 max_tokensconfig.max_tokens, # 默认 512适配嵌入模型上限 merge_peersTrue # 合并过小的相邻块 )核心思路是结构感知 词元精确块边界尊重段落、章节、表格等语义边界而不是机械地按字符数切割contextualize()会把标题层级heading hierarchy注入每个块保证块脱离原文档后仍具备上下文。这也对应教程脚本 04_hybrid_chunking.py 演示的内容——它以 512 token 为上限对technical-architecture-guide.pdf分块输出块数、总 token 数、均值/极值及 token 分布统计并保存带上下文的分块结果到output/output_chunks.txt。如果 DoclingDocument 不可用或分块失败chunker.py还内置了滑动窗口兜底分块按句号/换行找边界与段落式 SimpleChunker可通过use_semantic_splitting配置切换。5.3 嵌入与存储embedder.py schema.sqlingestion/embedder.py 默认使用text-embedding-3-small1536 维支持批量嵌入batch_size100、限流指数退避重试、超长文本截断并带一个简单的 LRU 风格内存缓存EmbeddingCache减少重复 API 调用。数据库侧由 sql/schema.sql 定义documents表存原始文档与元数据chunks表存文本块、vector(1536)嵌入向量、chunk_index与token_count并建立ivfflat (vector_cosine_ops)向量索引。核心查询函数match_chunks()用余弦距离计算相似度SELECT c.id, c.document_id, c.content, 1 - (c.embedding query_embedding) AS similarity, d.title AS document_title, d.source AS document_source FROM chunks c JOIN documents d ON c.document_id d.id WHERE c.embedding IS NOT NULL ORDER BY c.embedding query_embedding LIMIT match_count;5.4 检索问答rag_agent.pyrag_agent.py 用 PydanticAI 定义了一个注册了search_knowledge_base工具的 Agent查询先经embed_query()生成嵌入再调用match_chunks()取 top-k 相关块默认 5结果带来源标题格式化后交给 LLM 生成带引文的回答交互层使用run_stream逐 token 流式输出。启动命令uv run python cli.pyCLI 提供help、clear、stats、exit/quit等命令启动时会做数据库健康检查。六、进阶能力与调优方向除了基础转换docling_basics/README.md 还记录了三个可选增强点图片描述pipeline_options.do_picture_description True并配置granite_picture_description用 IBM Granite Vision 自动生成图片/图表说明让视觉内容也可被检索代码理解do_code_enrichment True保留语法高亮、代码块识别与语言检测适合处理含代码的技术文档本文样例正是此类文档表格结构识别table_structure_options.mode TableFormerMode.ACCURATE提升复杂/跨页表格的抽取精度。音频场景则由 03_audio_transcription.py 演示通过AsrPipelineOptionsasr_model_specs.WHISPER_TURBO配置 Docling 的 ASR 管线把 MP3/WAV/M4A/FLAC 转录为带[time: 0.0-4.0]时间戳标记的 Markdown需要系统安装 FFmpeg使播客、访谈等音频内容同样可进入 RAG 知识库。七、小结以technical-architecture-guide.pdf为样本可以看出Docling 的价值在于把转换从信息丢失的瓶颈变成 RAG 质量的第一道保障——它既保住了表格、代码块、层级标题这些传统解析器最容易丢的结构又通过 HybridChunker 让分块天然适配嵌入模型的 token 限制。而 docling-rag-agent 仓库则给出了从这第一步到最后问答的完整参考实现docling_basics/四个渐进式教程负责理解能力边界ingestion/三件套ingest.py、chunker.py、embedder.py负责工程落地schema.sql 与 rag_agent.py 负责检索与问答闭环。遇到复杂版式文档的 RAG 场景这条路径可以直接复用。【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考