Oqura.ai local-datagen-cli：将本地文档变成 LLM 训练数据的利器

从"我有好数据但不会用"说起

如果你是 AI 开发者，一定有过这样的经历：手头积累了大量内部文档——产品手册、技术文档、会议纪要、客户 FAQ——这些数据质量极高，恰恰是训练垂直领域 LLM 的宝贵素材。然而，当你真正动手想把它们变成训练数据时，问题接踵而至：PDF 怎么批量提取文本？Word 里的表格如何结构化？图片中的文字怎么识别？好不容易导出了内容，格式又乱七八糟，还要人工一条条标注问答对……

一个人标注 1000 条高质量 QA 对，至少需要两到三天。 如果是专业领域（医疗、法律、金融），成本更高。Oqura-ai/local-datagen-cli 就是为了解决这个问题而生的——它把上述全部流程自动化，你只需要告诉它"我要什么格式的数据"，剩下的交给 AI Pipeline。

技术背景：合成数据为什么火了

2024 年以来，合成数据（Synthetic Data）成为 LLM 训练领域的关键词。OpenAI 的 GPT-4.1 系列、Anthropic 的 Claude 系列，背后都有大量合成数据参与训练。这是因为高质量人类标注数据越来越稀缺，而合成数据配合合适的质量过滤策略，已经能在多项任务上逼近甚至超越纯人工标注数据。

与此同时，本地化数据处理的需求也在增长。企业不愿将内部文档上传到第三方服务器，数据安全和隐私合规是核心诉求。local-datagen-cli 恰好踩在这两个趋势的交汇点上——所有文件处理在本地完成，只有文本内容被发送给云端 AI API，生成的数据完全归用户所有。

类比理解：它就像一个"智能厨师"

把 local-datagen-cli 想象成一个智能厨房流水线：

• 输入食材：PDF、Word、图片、PPT、纯文本（你公司的各种文档）
• 切菜台（Mistral OCR）：把图片和扫描件转成文字，把 Word/PDF 里的内容提取出来
• 食材冷藏室（Qdrant 向量数据库）：把所有文字切成小块（chunk），用语义向量索引起来
• 配方生成器（Schema Agent）：你告诉它"我要一个 FAQ 数据集，每个问答要包含问题、答案、难度等级、类型"，它自动生成数据结构定义
• 主厨（Generation Agent / GPT-4.1-mini）：根据配方，从冷藏室里挑相关食材，组合加工成一道道成品
• 摆盘输出（Pydantic 校验）：确保每道菜都符合你的格式要求，格式不对直接打回重做

整个过程，你只需要在终端回答几个问题，敲回车即可。

核心功能与技术实现

支持的输入格式

local-datagen-cli 支持六种本地文件格式，覆盖了绝大多数办公文档场景：

格式	处理方式	适用场景
PDF	PyMuPDF 提取文本页	正式文档、报告
DOCX/DOC	python-docx 解析段落	Word 文档
JPG/PNG/GIF	Mistral OCR 识别文字	扫描件、截图
TXT/MD	直接读取，按行分页	纯文本、Markdown
PPTX	python-pptx 提取每页文本	演示文稿

所有格式最终都会被统一转换为 PDF，再由 Mistral OCR 提取内容——这是项目选用的"统一中间格式"策略，保证了处理逻辑的一致性。

Multi-Agent Pipeline 架构

项目的核心代码分布在四个 Python 模块中：

workflow.py — 主流程编排者，负责文件格式转换、PDF 分页、OCR 调用、Qdrant 索引、最终数据集生成。其中 convert_to_pdf() 函数实现了统一格式转换，process_page() 函数负责单页内容提取。

agents/schema_agent.py — 使用 OpenAI 的 responses.parse 接口（结构化输出），接收用户描述的数据格式需求，生成 Pydantic Schema 定义（如问题字段、答案字段、难度等级等），保证输出数据有严格类型约束。

agents/generation_agent.py — 数据生成引擎，调用 GPT-4.1-mini，根据上下文 chunk 和 Schema 生成符合格式的 JSON 数据。用 Pydantic DatasetRecords 做输出校验，JSON 解析失败或格式不匹配会重试 3 次。

qdrant_setup.py — 向量数据库初始化，使用 Qdrant Client + FastEmbed 嵌入模型，将文档 chunk 转换为向量，实现语义相似性检索。

Qdrant 向量检索的妙用

传统的做法是把整个文档扔给 LLM，让它从中提取信息——这对长文档来说既贵又慢。项目采用滑动窗口 + 向量检索的策略：把文档按页切分，每页独立 OCR 提取，存入 Qdrant。当用户要求生成某类数据时，系统在向量空间中搜索最相关的若干 chunk 作为上下文，而不是喂整个文档。这既降低了 API 调用的 token 消耗，也提升了生成内容的相关性。

数据演化增强（Evolution Agent）

项目包含 evolution_agent 子目录（evolver.py），对生成的数据进行"演化"处理——例如将简单问答改写为复杂问法、增加同义词替换、生成对抗性问答等，提升数据集的多样性和难度梯度。这是微调高质量模型（如生产级别的客服机器人）时非常关键的一步。

部署与上手体验

部署步骤

项目不提供 Dockerfile，不支持纯 Docker 一键部署，这是它最主要的部署门槛。正确部署流程如下：

第一步：安装依赖

git clone https://github.com/Oqura-ai/local-datagen-cli
cd local-datagen-cli
pip install -r requirements.txt

requirements.txt 中包含了 15 个直接依赖，其中 qdrant-client[fastembed] 包含了向量嵌入模型（依赖较大），openai、mistralai、pymupdf 是核心 AI 和文档处理库。

第二步：启动 Qdrant 向量数据库

docker-compose up -d

docker-compose.yaml 中定义了 Qdrant 服务，端口 6333（gRPC）和 6334（REST），数据持久化到 qdrant_data/ 目录。

第三步：配置 API Key

cp .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY 和 MISTRAL_API_KEY

第四步：运行主程序

python main.py

终端会显示 ASCII 艺术 banner，交互式引导用户输入文档目录路径和数据格式描述。

上手门槛评估

维度	评估
编程要求	中等：需要能读写 Python、配置 API Key、理解向量数据库基本概念
部署难度	中等：docker-compose 简单，但依赖较多，首次安装约 10-20 分钟
费用	中等：OpenAI GPT-4.1-mini 按 token 计费，Mistral OCR 按调用计费；Qdrant 本地运行无费用
硬件要求	4GB RAM 最低（推荐 8GB+），不需要 GPU

对于没有 AI 基础的团队成员，有一定门槛——需要理解"向量数据库"和"API Key"的概念，不适合纯业务人员独立使用。

局限与争议

1. 依赖云端 API，数据隐私并非绝对安全

项目在 README 中强调"本地文件处理"，但文本内容仍需发送到 OpenAI 和 Mistral 的服务器。对于极高安全要求（如金融监管数据、医疗患者记录），这可能不满足合规要求。期待后续支持本地 LLM（如 Ollama）作为替代方案。

2. OCR 质量受文档质量影响大

Mistral OCR 对印刷体文档识别效果优秀，但对手写体、低分辨率扫描件、表格密集型文档的表现会明显下降。生成数据的质量上限，实际上由 OCR 的识别准确率决定。

3. 缺少测试文件

项目仓库中没有 tests/ 目录，所有 Python 代码均无单元测试覆盖。对于需要长期维护的项目来说，这是明显的技术债务。

4. Evolution Agent 处于早期阶段

evolution_agent 子模块代码量有限，数据演化策略相对基础，生成的对抗性样本多样性可能不足以支撑生产级微调任务。

行业意义与增长空间

截至目前，该项目拥有 83 stars、12 forks，在 GitHub 的 AI 数据集工具类目中属于早期项目，但从技术选型和解决的问题域来看，具有不错的实用价值：

• Qdrant + OpenAI Responses API 的组合代表了当前合成数据生成的主流技术路径
• Multi-Agent Pipeline 架构将数据生成的各个环节解耦，便于独立优化和扩展
• Schema-Driven Generation（Schema Agent + Pydantic 校验）是目前最可靠的结构化输出方案之一

从趋势看，随着更多垂直领域 LLM 微调需求的爆发，类似的数据准备工具会越来越受关注。该项目的增长空间在于：支持更多输入格式（Email、网页、录音转写）、集成更多本地 LLM 选项、丰富 Evolution Agent 的数据增强策略。

快速开始

# 克隆项目
git clone https://github.com/Oqura-ai/local-datagen-cli
cd local-datagen-cli

# 安装依赖
pip install -r requirements.txt

# 启动 Qdrant
docker-compose up -d

# 配置 API Key
cp .env.example .env
# 编辑 .env 填入 OPENAI_API_KEY 和 MISTRAL_API_KEY

# 运行
python main.py

---

本分析由 Hermes Agent 自动生成，基于 GitHub API 采集的项目代码和文档。如有疏漏欢迎反馈。