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

文档：`format.py` 代码详解

文件概述

本文件主要实现了从文本中提取结构化问答（QA）对象的相关工具函数。其核心功能是：无论输入文本是标准 JSON 格式、嵌入在代码块中的 JSON，还是半结构化的文本（如带有特定字段的字符串），都能尽可能地解析出包含摘要（Summary）和问答对（PossibleQA）的标准化数据结构。这为后续的问答系统、知识抽取、数据清洗等任务提供了坚实的基础。

主要函数说明

1. `extract_qa_object`

这是整个模块的入口函数，负责从输入文本中提取出 QA 对象。其实现思路如下：

首先调用 extract_json_content，尝试从文本中提取出被 ```json 代码块包裹的内容。如果找到了，则优先使用这部分内容作为 JSON 解析的目标。
尝试用 json.loads 解析提取到的内容。如果解析成功，直接返回解析结果。
如果 JSON 解析失败，则进入异常处理流程，调用 extract_json_manually 进行手动提取。该方法通过正则表达式从文本中抽取出 "Summary"、"Question"、"Answer" 字段，并组装成标准结构。
如果手动提取也失败，则返回一个默认的空对象，保证了函数的健壮性和容错性。

这种分层次、递进式的提取策略，极大提升了对多样化输入格式的适应能力。

2. `extract_json_content`

该函数用于从文本中提取被 json 代码块包裹的内容。其原理是利用正则表达式，查找形如json ... ``` 的片段，并返回其中的内容。如果找不到，则返回原始文本。这样设计的好处是，既能兼容标准 JSON 文本，也能适应 Markdown 等文档中常见的代码块嵌入格式。

3. `extract_json_manually`

当标准 JSON 解析失败时，该函数通过正则表达式，手动从文本中提取出 "Summary"、"Question"、"Answer" 字段。其具体流程为：

分别定义用于匹配摘要、问题、答案的正则表达式。
分别查找摘要、所有问题、所有答案。
检查提取到的内容是否完整且一一对应（即问题数和答案数相等，且都不为空）。
如果校验通过，则将摘要和问答对组装成标准结构返回；否则返回 None。

这种手动提取方式，虽然不如标准 JSON 解析严谨，但在面对格式不规范或部分损坏的数据时，能最大程度地挽救有用信息。

4. `extract_markdown_content`

该函数用于从文本中提取被 ``markdown 代码块包裹的内容。其实现方式与extract_json_content` 类似，利用正则表达式查找所有 markdown 代码块，并将其内容拼接返回。如果找不到，则返回原始文本的去首尾空白版本。该函数适用于需要从富文本或文档中提取纯 Markdown 内容的场景。

实现原理与设计考虑

1. 多层次容错与健壮性

整个模块的设计充分考虑了实际数据的多样性和不规范性。通过优先尝试标准 JSON 解析、再退而求其次地手动提取，极大提升了对异常数据的容忍度，保证了系统的健壮性和实用性。

2. 正则表达式的灵活应用

正则表达式在手动提取阶段发挥了关键作用。通过灵活的模式匹配，可以从半结构化甚至部分损坏的文本中提取出有用信息。这对于实际生产环境中面对的“脏数据”尤为重要。

3. 兼容多种输入格式

无论输入是纯 JSON、嵌入在代码块中的 JSON，还是带有特定字段的文本，模块都能尽量提取出标准化的 QA 对象。这种兼容性为上游数据采集、下游数据处理提供了极大的便利。

4. 明确的返回结构

所有提取函数最终都返回包含 "Summary" 和 "PossibleQA" 的标准字典结构，便于后续处理和接口对接。

应用场景

该模块适用于知识库构建、问答系统、数据清洗、文本解析等多种场景。尤其在面对来源多样、格式不一的原始数据时，能够自动化地提取出结构化的问答信息，为后续的 NLP 任务打下坚实基础。

代码示例

text = '''
```json
{
    "Summary": "关于AI的简介",
    "PossibleQA": [
        {"Question": "什么是AI？", "Answer": "人工智能的简称。"},
        {"Question": "AI有哪些应用？", "Answer": "语音识别、图像识别等。"}
    ]
}

''' qa_obj = extract_qa_object(text) print(qa_obj)

输出: {'Summary': '关于 AI 的简介', 'PossibleQA': [{'Question': '什么是 AI？', 'Answer': '人工智能的简称。'}, ...]}


---

## 总结

`format.py` 通过分层次的提取策略、灵活的正则表达式应用和健壮的异常处理机制，实现了对多样化文本中QA对象的高效提取。其设计兼顾了实用性、健壮性和兼容性，是文本结构化处理流程中的重要基础模块。

文档：format.py 代码详解