RAGFlow框架优化经验分享（附代码）：图文识别+动态分块、API调优+源码修改-CSDN博客

本文链接：https://blog.csdn.net/m0_59235945/article/details/147904544

很高兴能了解到很多之前没涉猎过的行业和场景，其中经常被集中问到的问题大概有四个：中小企业做RAG知识库落地选择框架哪个比较好？如果选择 RAGFlow 如何进行定制化开发？如何对文档中的图片进行识别检索？如何对复杂文档进行动态分块等。

RAG并没有“一招鲜”的神奇魔法，传说那几个大厂手里掌握的RAG”核心技术“，私以为也是经过了必要且复杂的“策略优化-管道设计-训练-调优-发布”等专业开发流程，不过成熟的开源应用框架，无疑是更有想象空间的社会化大创新。

1.优化实施路线图

以上篇介绍的机械加工行业的维保场景为例[RAGFlow+DeepSeek-R1:14b落地案例分享（足够详细）：机加工行业设备维保场景]，推荐先采用官方的 Python API 进行合理的优化配置后，再修改项目源码，最后根据业务目标做必要的高级优化拓展。此处附上一张个人项目实施过程中积累的些优化要点，供各位参考：

*1.1*

*阶段一：API 优化配置*

配置不同文档类型的解析策略

调整检索参数优化语义搜索质量

定制大模型提示词以适应机械行业特点

*1.2*

*阶段二：基础源码修改*

实现专业术语处理模块

开发查询路由机制

增加上下文增强功能

*1.3*

*阶段三：高级优化扩展*

实现多级索引结构

开发高性能缓存机制

添加查询日志分析系统

*2*

6 个官方 Python API 优化全解析

根据 RAGFlow 官方 Python API 文档，为大家完整梳理了所有可进行 API 优化的模块和参数。这些 API 调优可以不修改源码，直接通过参数配置实现性能提升。

建议在看完之后还是去官网看下原文，亲自动手试过一遍会有不一样的体感。原文出处：

https://ragflow.io/docs/dev/python_api_reference

*2.1*

*数据集管理*

*创建数据集 create_dataset*

RAGFlow.create_dataset(    name: str,    avatar: str = "",    description: str = "",    embedding_model: str = "BAAI/bge-large-zh-v1.5",    language: str = "English",    permission: str = "me",     chunk_method: str = "naive",    parser_config: DataSet.ParserConfig = None)

优化参数：

embedding_model: 选择合适的嵌入模型，影响检索质量

中文场景推荐: “BAAI/bge-large-zh-v1.5”

英文场景可选: “BAAI/bge-large-en-v1.5”

language: 选择与文档匹配的语言
chunk_method: 关键参数，根据文档类型选择最佳分块策略

“naive”: 通用文档

“paper”: 论文/设备手册

“book”: 结构化书籍

“table”: 表格数据

“qa”: 问答格式文档

“picture”: 图片文档

“one”: 整个文档作为一个块

“knowledge_graph”: 知识图谱

parser_config: 精细调整解析配置

chunk_token_num: 控制分块大小

delimiter: 自定义分隔符

layout_recognize: 是否启用布局识别

raptor: 高级解析选项

*更新数据集 DataSet.update*

DataSet.update(update_message : dict)

**优化参数:****

embedding_model: 更换更适合的嵌入模型

chunk_method: 调整分块策略

meta_fields: 更新元数据字段

*2.2*

*文件管理 (FILE MANAGEMENT)*

*上传文档 DataSet.upload_documents*

DataSet.upload_documents(document_list : list[dict])

优化参数:

display_name: 文件显示名，方便检索与管理

blob: 文件内容

*更新文档 Document.update*

Document.update(update_message : dict)

优化参数:

chunk_method: 文档分块方法
parser_config: 文档解析配置

对于图文文档，可设置: “layout_recognize”: True

对于表格文档，可设置: “html4excel”: True

*解析文档*

DataSet.async_parse_documents(document_ids : list[str])

用于触发文档解析流程，支持批量处理。

*2.3*

*分块管理 (CHUNK MANAGEMENT)*

*添加分块 Document.add_chunk*

Document.add_chunk(content: str, important_keywords: list[str] = [])

优化参数:

important_keywords: 关键词标注，增强检索相关性

*更新分块 Chunk.update*

Chunk.update(update_message : dict)

优化参数:

content: 更新分块内容

important_keywords: 更新关键词

available: 控制分块可用性

*检索 RAGFlow.retrieve(关键API)*

RAGFlow.retrieve(    question: str = "",    dataset_ids: list[str] = None,    document_ids: list[str] = None,    page: int = 1,    page_size: int = 30,    similarity_threshold: float = 0.2,    vector_similarity_weight: float = 0.3,    top_k: int = 1024,    rerank_id: str = None,    keyword: bool = False,    highlight: bool = False)

优化参数 (最重要的检索相关参数):

similarity_threshold: 相似度阈值，影响召回范围
vector_similarity_weight: 向量相似度权重与关键词匹配权重的比例

设置为 0-1 之间，值越大向量权重越高

工业领域建议参考0.3-0.5，平衡专业术语与语义理解

top_k: 参与向量检索的 chunk 数量，影响检索范围
rerank_id: 重排序模型 ID，提升检索精度
keyword: 开启关键词匹配，对专业领域极其有用
highlight: 高亮匹配内容，帮助理解匹配原因

*2.4*

*聊天助手管理*

*创建聊天助手 RAGFlow.create_chat*

RAGFlow.create_chat(    name: str,     avatar: str = "",     dataset_ids: list[str] = [],     llm: Chat.LLM = None,     prompt: Chat.Prompt = None)

优化参数:

llm: LLM 模型配置

model_name: 模型名称

temperature: 温度，影响创造性

top_p: 词汇采样范围

presence_penalty: 重复惩罚

frequency_penalty: 频率惩罚

max_token: 最大输出 token 数

prompt: 提示词配置

similarity_threshold: 相似度阈值

keywords_similarity_weight: 关键词相似度权重

top_n: 提供给 LLM 的 chunk 数量

rerank_model: 重排序模型

top_k: 重排序参与的候选数量 empty_response: 无匹配时的回复

show_quote: 是否显示引用来源

prompt: 系统提示词内容

*更新聊天助手 Chat.update*

Chat.update(update_message : dict)

优化参数: 同 create_chat 中的参数

*2.5*

*会话管理 (SESSION MANAGEMENT)*

*创建会话 Chat.create_session*

Chat.create_session(name: str = "New session")

*提问 Session.ask*

Session.ask(question: str = "", stream: bool = False, **kwargs)

优化参数:

stream: 流式输出，提升用户体验

**kwargs: 可传递给 prompt 中定义的变量

*2.6*

*代理管理 (AGENT MANAGEMENT)*

*创建代理会话 Agent.create_session*

Agent.create_session(id, rag, **kwargs)

*代理提问 Session.ask*

Session.ask(question: str = "", stream: bool = False)

*与普通会话的ask方法类似。*

*3*

调整项目源码思路参考

*3.1*

*专业术语处理*

需要在检索引擎层面添加工业领域同义词和术语映射：

# 需要修改源码的示例逻辑class CustomTerminologyProcessor:    def __init__(self, terminology_mapping):        self.terminology_mapping = terminology_mapping  # 同义词映射表
    def process_query(self, query):        # 专业术语标准化        # 车间俚语转换为标准术语        processed_query = query        for slang, standard_term in self.terminology_mapping.items():            processed_query = processed_query.replace(slang, standard_term)        return processed_query

修改点：

在查询预处理阶段添加定制的术语处理模块

需要在 RAGFlow 的查询管道中修改源码添加此功能

*3.2*

*多级索引结构实现*

需要定制 Milvus 索引策略，实现基础索引层和语义索引层的混合索引：

# 这部分需要修改源码，以下是概念性代码class CustomHybridIndexBuilder:    def __init__(self, vector_db_client):        self.client = vector_db_client
    def create_scalar_indices(self, collection_name, fields):        # 创建设备编号、故障代码等标量索引        for field in fields:            self.client.create_index(collection_name, field, "scalar")
    def create_vector_indices(self, collection_name, fields):        # 创建向量索引        for field in fields:            self.client.create_index(collection_name, field, {"index_type": "HNSW", "params": {"M": 16, "efConstruction": 200}})

修改点：

修改 RAGFlow 的索引构建模块扩展

Milvus 客户端接口以支持多索引策略

*3.3*

*查询路由设计*

需要实现定制化的查询路由逻辑，识别不同类型的查询并路由到最合适的检索通道：

# 查询路由器 - 需要源码修改实现class QueryRouter:    def route_query(self, query_text):        if self._is_equipment_code(query_text):            return "exact_match", {"field": "equipment_code"}        elif self._is_fault_code(query_text):            return "exact_match", {"field": "fault_code"}        elif self._is_parameter_query(query_text):            return "parameter_lookup", {"field": "parameter_name"}        else:            return "semantic_search", {"model": "embedding_model"}

修改点：

在 RAGFlow 的查询处理流程中添加查询分类和路由机制

实现针对不同查询类型的专用处理通道

*3.4*

*上下文增强机制*

增加查询上下文增强，融入设备信息、历史记录等：

# 上下文增强器 - 需要修改源码实现class ContextEnhancer:    def enhance_query(self, query, session_history, equipment_metadata=None):        # 添加设备上下文信息        if equipment_metadata:            query_context = f"设备型号: {equipment_metadata['model']}, 生产年份: {equipment_metadata['year']}\n"            query_context += query
        # 添加历史查询信息        if session_history:            relevant_history = self._extract_relevant_history(session_history, query)            query_context = f"参考历史信息: {relevant_history}\n" + query_context
        return query_context

修改点：

修改会话管理模块，实现会话状态跟踪

增加设备元数据关联机制

在查询处理流程中加入上下文增强步骤

*4*

图文结合文档处理方案

依然是两种方案，直接使用RAGFlow API方案优势是更简单，使用现有功能，无需额外的模型调用，也能够直接显示原始图片，视觉效果更好，处理速度更快，不依赖外部 API，当然成本也无疑更低。

但使用一个多模态模型进行预处理的方案优势也很明显，图片内容被转换为文本，便于向量化和语义搜索，也可以依托多模态模型的能力，提供更丰富的图片内容解释。

目前实际测试下来，采用两种方案的组合，效果更加稳定。

*4.1*

*使用多模态预处理生成图片描述*

# 使用多模态模型生成图片描述processor = MultimodalDocumentProcessor(api_key="YOUR_API_KEY")enhanced_docs = processor.process_pdf("设备手册.pdf")

*4.2*

*使用 RAGFlow 处理和存储原始图片*

# 配置保留图片的数据集dataset = rag_object.create_dataset(    name="图文设备手册",    chunk_method="paper",    parser_config={"layout_recognize": True})
# 上传原始PDF文档with open("设备手册.pdf", "rb") as f:    dataset.upload_documents([{"display_name": "设备手册.pdf", "blob": f.read()}])

*4.3*

*创建能够提供文本描述和图片引用的助手*

assistant = rag_object.create_chat(    name="图文设备专家",    dataset_ids=[dataset.id],    prompt=Chat.Prompt(        prompt="""你是设备维修专家。回答时，请同时提供:        1. 文字描述解释故障和解决方案        2. 引用相关图片，包括图片描述        3. 告诉用户可以参考哪些图片获取更多信息        {knowledge}"""    ))

*4.4*

*源码修改的一些建议*

*增强图片提取和处理：*

修改 PDF 解析器，更准确地绑定文本和相关图片

增加图片内容分析功能，自动标注图片类型（如"故障图"、"结构图"等）

*实现图文混合索引：*

为图片创建特殊索引，支持通过图片内容或相关文本检索图片

在检索结果中包含图片 URL 或直接嵌入图片

*改进响应生成：*

修改聊天助手的响应生成逻辑，自动识别图片引用

在生成的回答中包含相关图片或图片链接

*5*

动态分块策略参考

RAGFlow的chunk_method参数是在数据集级别或文档级别设置的，不支持在单个文档内部动态切换不同的分块策略。但实际情况是，同一文档中的不同部分可能需要不同的处理方式，比如针对段落、图片、表格、图表等，使用单一的分块策略很难同时兼顾所有这些内容类型的特点。

*5.1*

*4种分块策略对比*

*源码修改方案：*

修改 RAGFlow 的文档解析器，使其能够识别文档中的不同部分并应用不同的分块策略，但这需要深入修改 RAGFlow 的核心处理逻辑，如果没有深入理解RAGFlow的全局代码，建议不要这么做。

*文档预处理方案：*

在上传到 RAGFlow 前预处理文档，将其拆分成不同类型的子文档。例如，将设备手册拆分为纯文本部分、表格部分、图文部分等然后分别上传到不同的数据集，每个数据集使用适合的分块策略。

这个方案优点是，可以充分利用RAGFlow针对不同内容类型的专门分块策略，但问题也很明显，就是文档上下文被拆分，可能影响整体理解。

*自定义分块方案：*

不使用RAGFlow 的自动分块，而是手动控制分块，使用chunk_method="one"将整个文档作为一个块导入，然后使用自定义逻辑创建更细粒度的分块。这种做法无疑可以实现最精细的控制、保留文档完整性，当然缺点就是实现上会相对麻烦。

*混合模型方案：*

创建多个使用不同分块策略的数据集，将同一文档上传到所有这些数据集，在检索时查询所有数据集并合并结果。这种方法保持文档完整性，但创建多个使用不同分块策略的副本，会造成存储冗余，检索时需要合并多个结果集。

*5.2*

*推荐自定义方案*

这种方法使用RAGFlow的API但完全控制分块过程，最灵活且无需修改源码。

*完整保留原始文档:*

使用 chunk_method="one"将文档整体上传保留文档的完整性和上下文关系

*自定义内容识别:*

使用 PyMuPDF 识别文档中的不同内容类型:

文本、段落、表格内容图片及其相关描述、章节标题和结构

*动态创建精细分块:*

文本块: 基于段落和语义分界

表格块: 保留表格结构和行列关系

图文块: 关联图片和周围的描述文本

*添加分块类型标记:*

每个分块添加类型标识符[text], [table], [image]等

方便检索时区分不同类型的内容

*丰富关键词提取:*

为每个分块提取相关关键词

保留章节上下文信息

回顾23年和24年国内大部分中小企业对大模型应用落地的态度，大抵是23年在观望，24年上半年利润和数字化底座都不错企业开始内部小范围试错，发现效果不达预期后，要么放弃，要么就试图寻找一些外部解决方案。但对于大部分公司而言，大模型在企业应用落地受限于比较贵的部署成本和复杂的技术门槛迟迟没有提上日程，DeepSeek的1/20开源之后，正在改变这一局面，此刻我们或许也正处于一个关键的转折点之上。

如何学习大模型 AI ？

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

在这里插入图片描述