Skip to content

以下是对 gc-qa-rag/ragapp/etl_doc/generate_full.py 文件的详细 Markdown 文档说明：

文档：generate_full.py 代码详解

文件概述

本文件实现了一个完整的文档问答生成流程，核心功能是：针对每个用户问题，结合相关文档内容，自动生成高质量的答案，并以 Markdown 格式输出。该流程广泛应用于知识库自动构建、智能问答系统等场景。代码结构清晰，采用了数据类（dataclass）进行数据建模，模块化地实现了数据加载、处理、生成和保存等各个环节，具备良好的可维护性和扩展性。

主要类与函数说明

1. 数据结构建模

  • QAPair
    表示单个问答对，包含 question 和 answer 字段。通过 from_dict 方法支持从字典结构快速构建，便于与 JSON 数据对接。

  • Chunk
    表示一组问答对（possible_qa），通常对应于同一文档或同一主题下的多个问题。支持从字典结构批量构建问答对列表。

  • Document
    表示原始文档，包含 HTML 格式的内容（content_html），可选的纯文本内容（content_text）。同样支持从字典结构构建。

2. FullDocGenerator 核心流程

初始化与路径管理

  • 构造函数接收一个 EtlContext，用于确定根目录、产品名、文件索引等上下文信息。
  • _get_file_paths 方法统一管理问答数据、文档数据和输出目录的路径拼接，保证了路径的可维护性和一致性。
  • _ensure_directories_exist 方法确保所有相关目录存在，避免后续文件操作出错。

数据加载

  • _load_document 负责从指定路径加载文档内容，并解析为 Document 对象。异常时记录日志并返回 None。
  • _load_qa_data 负责加载问答数据，解析为 Chunk 列表。异常时同样记录日志并返回 None。

文档内容提取

  • _get_html_main_content 利用 BeautifulSoup 从 HTML 文档中提取主要内容（class 为 main__doc 的元素），并以换行符拼接。若未找到目标元素，则记录警告日志。这一设计保证了生成答案时只关注文档的核心内容，提升了答案的相关性和简洁性。

答案生成

  • _generate_answer 负责将用户问题和文档内容拼接成标准化的 prompt，调用 LLM（如 chat_to_llm）生成答案。异常时记录错误日志并返回空字符串。Prompt 模板采用了结构化的格式，明确区分“用户问题”和“相关文档”，有助于提升大模型生成答案的准确性和可控性。

答案保存

  • _save_answer 负责将生成的答案以 Markdown 格式保存到指定路径。异常时记录错误日志。

主流程 generate

  • 依次完成路径准备、数据加载、输出目录清理等准备工作。
  • 遍历每个问答分组（chunk）和每个问答对（qa_pair），为每个问题生成答案，并保存为独立的 Markdown 文件，文件名中包含索引信息，便于后续检索和溯源。
  • 过程中详细记录日志，便于问题排查和流程追踪。

3. 启动函数

  • start_generate_full_doc 是对外暴露的启动入口，接收上下文参数，实例化生成器并启动主流程。

实现原理与设计考虑

1. 数据与流程解耦

通过数据类（dataclass）对问答对、问答分组、文档等核心数据结构进行建模，极大提升了代码的可读性和可维护性。主流程与数据加载、保存、内容提取等细节解耦，便于后续扩展和单元测试。

2. 健壮性与容错

所有关键的文件操作、数据解析、模型调用等环节均做了异常捕获和日志记录，保证了流程的健壮性。即使部分数据损坏或模型调用失败，也不会影响整体流程的继续执行。

3. 结构化 Prompt 设计

生成答案时采用结构化的 prompt，将“用户问题”和“相关文档”明确分区，输出格式要求为 Markdown。这种设计有助于提升大模型生成内容的针对性和可控性，便于后续的内容展示和二次处理。

4. 灵活的目录与文件管理

所有输入输出路径均通过上下文参数和统一方法管理，支持多产品、多批次的灵活扩展。输出文件以分组和问答索引命名，便于批量处理和结果追踪。

5. 日志与可追溯性

全流程详细记录日志，包括每一步的关键操作、异常信息、生成进度等，极大方便了问题定位和流程优化。

应用场景

该模块适用于大规模文档的自动问答生成、知识库构建、FAQ 自动化生成等场景。通过自动化地将结构化问答与原始文档结合，批量生成高质量的答案文本，为智能客服、企业知识管理、文档检索等系统提供了坚实的数据基础。

代码示例

from ragapp.common.context import EtlContext
from gc-qa-rag.ragapp.etl_doc.generate_full import start_generate_full_doc

context = EtlContext(root="/path/to/project", product="my_product", index="001")
start_generate_full_doc(context)
# 运行后将在指定目录下生成每个问题的 Markdown 答案文件

总结

generate_full.py 通过模块化、结构化的设计，实现了文档问答自动生成的完整流程。其健壮的异常处理、灵活的路径管理、结构化的 prompt 设计和详细的日志记录，体现了对实际生产环境的深刻理解和工程化能力，是大规模知识自动化生成系统中的关键组件。