在评测大语言模型（LLM）应用时，问答对（QA Pairs）的准备工作常常令测试工程师感到棘手——如何从现有文档中高效提取出高质量的问题与答案，需要兼具业务知识、表达能力与理解能力。qagen 正是为解决这一痛点而诞生的开源工具，它能够自动生成并验证中文文档问答对，助您快速迈出LLM应用测试的第一步。
核心特性一览
qagen 具备以下六大核心优势：
- 多LLM支持：兼容 Ollama（本地部署）与 OpenAI（云端）模型
- 智能文档处理：自动分块，针对中文内容进行优化
- 多维度验证：涵盖语义相似度、关键词匹配、长度控制、唯一性检测
- 详细统计：生成质量报告与数据分析
- 中文优化：专为中文内容定制优化方案
- 灵活配置：丰富的参数选项，满足不同场景需求
安装
pip install qagen
小提示： 请确保您的 Python 版本为 3.8 及以上，并已正确配置所需的 LLM 服务（例如 Ollama 本地服务或 OpenAI API 密钥）。
快速开始
以下三种方式均可让您快速上手，请根据需求选择即可。
方法一：使用完整脚本（推荐）
运行完整的生成与验证流程：
# 运行完整的生成和验证流程
python examples/generate_and_validate_qa.py
方法二：使用简化脚本
仅生成 QA pairs，不进行验证：
# 仅生成QA pairs，不进行验证
python examples/generator_and_no_validate_qa.py
方法三：编程方式使用
from qa_gen_cn import generate_qa_pairs
# 基础使用
qa_pairs = generate_qa_pairs(
doc_path="your_document.txt",
llm_provider="ollama",
llm_model="llama3.1:8b"
)
常见问题： 运行脚本时提示“模块不存在”怎么办？请确认已执行 pip install qagen 安装成功，且安装后未移动或删除模块目录。
配置参数详解
通过灵活配置，您可以精准控制 QA 对的生成质量。
LLM 配置
使用 Ollama 示例：
# Ollama配置
llm_config = {
"llm_provider": "ollama",
"llm_model": "llama3.1:8b", # 或其他可用模型
"show_chunks": True, # 显示文档分块过程
"chunk_size": 500, # 文档块大小
"chunk_overlap": 50 # 块重叠大小
}
验证配置
小提示： 验证配置中的参数会影响验证的严格程度，建议根据文档内容与业务需求进行调整。
validation_config = {
# 语义相似度验证
"similarity_threshold": 0.3, # 相似度阈值（0-1）
"similarity_model": "paraphrase-multilingual-MiniLM-L12-v2",
}
高级使用示例
以下示例展示了通过编程方式完整控制生成与验证流程：
from qa_gen_cn.generator import QAGenerator
from qa_gen_cn.llm_factory import LLMFactory
from qa_gen_cn.validator import QAPairValidator
from qa_gen_cn.utils import load_document
# 1. 初始化LLM
llm = LLMFactory.create_llm(
provider='ollama',
model='llama3.1:8b',
temperature=0.7
)
# 2. 创建生成器
generator = QAGenerator(llm=llm, show_chunks=True)
# 3. 生成QA pairs
qa_pairs = generator.generate_from_document(
doc_path="your_document.txt",
chunk_size=3000,
chunk_overlap=100
)
# 4. 配置验证器
validator = QAPairValidator({
"similarity_threshold": 0.4,
'similarity_model':'paraphrase-multilingual-MiniLM-L12-v2'
})
# 5. 验证QA pairs
doc_content = " ".join([doc.page_content for doc in load_document("your_document.txt")])
validated_pairs = validator.validate(qa_pairs, doc_content)
print(f"生成 {len(qa_pairs)} 个QA pairs，验证通过 {len(validated_pairs)} 个")
小提示： temperature 参数控制生成内容的随机性，值越大答案越多样，但可能偏离原文。建议保持在 0.5~0.8 之间。
输出结果
运行完成后，会在 output 目录生成以下文件：
output/
├── qa_generation_result.json # 完整结果（包含配置、统计等）
├── qa_pairs.json # 纯QA pairs数据
└── statistics.txt # 统计报告
QA Pairs JSON 格式示例
[
{
"question": "什么是人工智能？",
"answer": "人工智能是计算机科学的一个分支，旨在创建能够模拟人类智能的机器。"
},
{
"question": "机器学习和深度学习的关系是什么？",
"answer": "机器学习是人工智能的分支，深度学习是机器学习的子集，使用神经网络进行学习。"
}
]
统计报告示例
=== QA Pairs 生成和验证统计报告 ===
文档路径: examples/1.txt
LLM配置: {'provider': 'ollama', 'model': 'llama3.1:8b'}
统计信息:
- 总生成数量: 25
- 验证通过数量: 18
- 验证通过率: 72.00%
- 平均问题长度: 23.4 字符
- 平均答案长度: 156.7 字符
验证配置:
- keyword_top_n: 15
验证机制详解
qagen 提供四重验证机制，确保生成的 QA 对质量。请注意：这四种验证是互斥的，一次只激活一个级别的验证。
1. 语义相似度验证
- 原理：使用多语言语义模型计算问题、答案与原文的相似度
- 作用：确保生成的 QA pairs 与原文内容高度相关
- 配置：
similarity_threshold（0-1，越高越严格）、similarity_model
2. 关键词匹配验证
- 原理：提取原文关键词，验证问题和答案是否包含相关关键词
- 作用：保证 QA pairs 涵盖文档核心内容
- 配置：
keyword_top_n（提取关键词数量）
3. 长度验证
- 原理：检查问题和答案的长度是否在合理范围内
- 作用：避免过短或过长的 QA pairs
- 配置：
question_min_length、question_max_length、answer_min_length、answer_max_length
4. 唯一性验证
- 原理：使用聚类算法检测重复的 QA pairs
- 作用：确保生成结果的多样性，避免冗余
- 配置：
similarity_model、uniqueness_check_enabled、uniqueness_distance_threshold（聚类距离阈值），建议范围 0.05-0.3 之间
常见问题： 为什么我同时配置了多个验证，有的却不起作用？因为四种验证是互斥的，优先级为：1 > 2 > 3 > 4。配置了更高优先级的验证后，低优先级的配置即使填写也不会生效。
特别注意事项
验证优先级及配置规则：
- 配置了
similarity_threshold和similarity_model（验证1），其他验证配置可不写，写了也不起作用。 - 配置了
question_min_length、question_max_length、answer_min_length、answer_max_length（验证2），后面的验证配置可不写，写了也不起作用。 - 配置了
keyword_top_n（验证3），后面的验证配置可不写，写了也不起作用。 - 配置了
similarity_model、uniqueness_distance_threshold和uniqueness_check_enabled（验证4），其他验证的配置可不写，写了也不起作用。
小提示： 如果希望获得最佳效果，建议先使用“仅生成不验证”模式快速观察输出，再根据结果调整验证策略。
常见问题解答（FAQ）
Q1：生成的 QA 对数量太少怎么办？
可以尝试减小 chunk_size 或减小 chunk_overlap，使文档分块更细，从而生成更多候选对。另外也可以降低验证阈值（如 similarity_threshold）或增大 uniqueness_distance_threshold。
Q2：验证通过率很低，如何优化？
首先检查文档内容是否清晰、结构是否完整。其次可适当降低验证的严格程度：例如将 similarity_threshold 从 0.3 调整为 0.2，或增加 question_max_length 限制。最后建议测试不同的 LLM 模型，不同模型对中文理解能力有差异。
Q3：使用 Ollama 时连接失败怎么办？
请确认 Ollama 服务已启动（默认在 localhost:11434），并且已经下载所需的模型（如 llama3.1:8b）。可以通过 ollama pull llama3.1:8b 提前拉取。
Q4：文档格式支持哪些？
目前支持纯文本（.txt）和部分常见格式。如果遇到编码问题，请确保文档使用 UTF-8 编码。
通过 qagen，您可以从繁琐的 QA 对手工制作中解放出来，将更多精力投入到 LLM 应用的评审与优化中。立即尝试，让文档自动“说话”吧！