DeepFabric 为语言模型和智能体评估生成合成训练数据。通过将推理轨迹与工具调用模式相结合，它能够创建高质量的领域特定数据集，教导模型如何有效思考、规划和行动，正确调用工具，并符合严格的模式结构。

DeepFabric 与其他数据集生成工具的不同之处在于，它利用独特的主题图生成算法，确保高多样性的同时保持领域相关的准确性。这种方法引导样本生成覆盖所有必要的子主题，同时避免冗余，而其他工具往往在这方面做得不够，导致模型过拟合。

受限解码和响应验证，以及在隔离的 WebAssembly 环境中执行真实工具，确保生成的样本严格遵守结构化模式、变量约束和执行正确性，从而保证数据集具有精确的语法和结构，可用于模型训练流程。工具定义可以直接从 MCP（模型上下文协议）服务器模式导入并自动模拟，也可以使用现实生活中的接口及一组常用工具（list_files()、'read_file() 等）。

一旦您的数据集生成完毕，可以自动上传到 Hugging Face，并直接导入到 TRL、Unsloth 和 Axolotl 等流行的训练框架中。

训练完成后，DeepFabric 内置的评估引擎会评估模型性能，使模型能够在来自训练分割的未见任务上证明其能力——涵盖仅用于评估的问题、答案和工具调用轨迹。

快速入门

DeepFabric 可以作为库、CLI 工具或通过 YAML 配置文件使用。以下是使用 CLI 的快速示例：

pip install deepfabric

export OPENAI_API_KEY="your-api-key"

deepfabric generate \
  --topic-prompt "Python编程基础" \
  --generation-system-prompt "你是一位Python专家" \
  --mode graph \
  --depth 3 \
  --degree 3 \
  --num-samples 9 \
  --batch-size 3 \
  --provider openai \
  --model gpt-4o \
  --output-save-as dataset.jsonl

此命令会生成一个主题图，并创建 27 个唯一节点，然后生成 27 个训练样本保存到 dataset.jsonl 文件中，从而实现 100% 的主题覆盖。

配置

DeepFabric 还使用 YAML 配置文件，包含三个主要部分以及可选的共享 LLM 默认设置。

[!NOTE]
下面的内容使用了模拟的工具执行，因此需要运行 Spin 服务，我们提供了一个 Docker 镜像：

docker run -d -p 3000:3000 ghcr.io/always-further/deepfabric/tools-sdk:latest`

将以下内容保存为 config.yaml：

# 可选：共享 LLM 默认设置（由主题和生成过程继承）
llm:
  provider: "openai"
  model: "gpt-4o"
  temperature: 0.7

# 主题：生成主题树/图
topics:
  prompt: "使用Python构建生产就绪的REST API"
  mode: tree                    # tree | graph
  depth: 3
  degree: 3
  save_as: "topics.jsonl"
  # 可选：覆盖共享 LLM 设置
  llm:
    model: "gpt-4o-mini"        # 在生成主题时使用更便宜的模型

# 生成：从主题中创建训练样本
generation:
  system_prompt: |
    您是一位精通 REST API 设计的 Python 后端开发专家。
    请创建实用且可直接投入生产的代码示例，并附上清晰的解释。
    示例应包含错误处理、类型提示，并遵循 PEP 8 编码规范。
    请使用以下工具在虚拟文件系统中读取、写入和列出文件：
    - read_file
    - write_file
    - list_files

  # 生成样本的附加说明
  instructions: |
    重点关注开发者在使用 Python 构建 REST API 时日常遇到的真实场景。
    包含正常流程和边界情况的处理。
    提供关于何时以及为何使用特定模式或库的背景信息。
    确保代码模块化、可测试且易于维护。

  # 配置工具时，代理模式会自动启用
  conversation:
    type: cot      # basic | cot
    reasoning_style: agent      # freetext | agent (for cot)

  # 工具配置（自动启用代理模式）
  tools:
    spin_endpoint: "http://localhost:3000"  # 用于执行工具的 Spin 服务
    components:                 # 将组件名称映射到工具名称
      builtin:                  # 路由至 /vfs/execute
        - read_file
        - write_file
        - list_files
    max_per_query: 3            # 每次查询允许使用的最大工具数量
    max_agent_steps: 5          # 最大 ReAct 推理迭代次数

  # 可选：在生成前将初始文件注入 Spin，用于工具调用
    scenario_seed:
      files:
        "Dockerfile": |
          FROM python:3.13
          WORKDIR /usr/local/app

          # 安装应用程序依赖项
          COPY requirements.txt ./
          RUN pip install --no-cache-dir -r requirements.txt

          # 复制源代码
          COPY src ./src
          EXPOSE 8080

          # 创建应用用户，避免容器以 root 用户运行
          RUN useradd app
          USER app

          CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]
        "main.py": |
          def greet(name):
              return f"Hello, {name}!"

          if __name__ == "__main__":
              print(greet("World"))
        "config.json": |
          {
            "version": "1.0.0",
            "debug": true,
            "max_retries": 3
          }

  # 生成控制与重试设置
  max_retries: 3                # 生成失败时的重试次数
  sample_retries: 2             # 样本验证失败时的重试次数
  max_tokens: 2000              # 每次生成的最大 token 数量

  # 可选：覆盖共享的 LLM 设置
  llm:
    temperature: 0.3            # 较低的温度以确保代码的一致性

# 输出：最终数据集配置
output:
  # 将纳入训练数据的系统提示
  # 这是训练后的模型将看到的系统消息
  system_prompt: |
    您是一位专注于 REST API 开发的 Python 编程助手。您提供清晰、可直接投入生产的代码及相应解释。
    始终考虑安全性、错误处理和最佳实践。

  include_system_message: true  # 是否在输出中包含系统消息
  num_samples: 4                 # 总共要生成的训练样本数
  batch_size: 3                 # 并行生成批次大小
  save_as: "api-dataset.jsonl"

 可选：上传至 Hugging Face
 huggingface:
   repository: "your-username/api-dataset-training-name"
   tags: ["python", "programming"]

通过加载 config.yaml 文件来运行生成：

deepfabric generate config.yaml

生成、训练、评估

DeepFabric 返回标准的 Hugging Face 数据集，便于与任何训练框架集成。

Colab 笔记本：

快速了解 DeepFabric 的实际操作方法，可通过 notebooks/ 文件夹中的笔记本或 Google Colab 来实现：

Qwen4b Blender MCP:

1. 生成数据集

deepfabric generate config.yaml --output-save-as dataset.jsonl

或者上传至 Hugging Face Hub：

deepfabric upload-hf dataset.jsonl --repo your-username/my-dataset

2. 加载并拆分用于训练

from datasets import load_dataset
from transformers import AutoTokenizer

# 从 Hub 加载数据集
dataset = load_dataset("alwaysfurther/deepfabric-generic-tools", split="train")

# 拆分为训练集和验证集
splits = dataset.train_test_split(test_size=0.1, seed=42)
train_ds = splits["train"]
eval_ds = splits["test"]

# 使用您的分词器进行格式化
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct")

def format_example(example):
    messages = [{k: v for k, v in msg.items() if v is not None}
                for msg in example["messages"]]
    return {"text": tokenizer.apply_chat_template(messages, tokenize=False)}

formatted_train = train_ds.map(format_example)

3. 使用 TRL 或 Unsloth 进行训练

from trl import SFTTrainer, SFTConfig

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=formatted_train,
    args=SFTConfig(output_dir="./output", num_train_epochs=3),
)
trainer.train()

4. 评估您的模型

from deepfabric.evaluation import Evaluator, EvaluatorConfig, InferenceConfig

config = EvaluatorConfig(
    inference_config=InferenceConfig(
        model_path="./output/checkpoint-final",  # 本地路径或 HF Hub ID
        backend="transformers",
    ),
)

evaluator = Evaluator(config)
results = evaluator.evaluate(dataset=eval_ds)  # 直接传入 HF 数据集

print(f"工具选择准确率: {results.metrics.tool_selection_accuracy:.2%}")
print(f"参数准确率: {results.metrics.parameter_accuracy:.2%}")
print(f"综合得分: {results.metrics.overall_score:.2%}")

评估

DeepFabric 提供了一套全面的评估体系，用于衡量您微调后的模型在工具调用任务上的表现。

基本评估

from datasets import load_dataset
from deepfabric.evaluation import Evaluator, EvaluatorConfig, InferenceConfig

# 加载您的评估数据集
dataset = load_dataset("your-username/your-dataset", split="test")

# 配置评估者
config = EvaluatorConfig(
    inference_config=InferenceConfig(
        model_path="./output/checkpoint-final",  # 本地路径或 HF Hub ID
        backend="transformers",                   // "transformers" 或 "ollama"
        temperature=0.1,                          // 低温以获得确定性输出
        max_tokens=2048,
    ),
    max_samples=100,           // 限制样本数量以便快速测试（None 表示全部）
    save_predictions=True,     // 保存单个预测结果
    output_path="eval_results.json",
)

// 运行评估
evaluator = Evaluator(config)
results = evaluator.evaluate(dataset=dataset)

// 打印总结
evaluator.print_summary(results.metrics)

# 清理 GPU 内存
evaluator.cleanup()

使用 LoRA 适配器进行评估

from deepfabric.evaluation import Evaluator, EvaluatorConfig, InferenceConfig

config = EvaluatorConfig(
    inference_config=InferenceConfig(
        model_path="Qwen/Qwen2.5-7B-Instruct",    # 基础模型
        adapter_path="./output/lora-adapter",     # LoRA 适配器路径
        backend="transformers",
        load_in_4bit=True,     # 4位量化
        max_seq_length=2048,
    ),
)

evaluator = Evaluator(config)
results = evaluator.evaluate(dataset=eval_dataset)

理解评估指标

评估器会为工具调用任务计算多个指标：

results = evaluator.evaluate(dataset=eval_dataset)
metrics = results.metrics

# 核心指标
print(f"已评估样本数: {metrics.samples_evaluated}")
print(f"已处理样本数: {metrics.samples_processed}")
print(f"处理错误数: {metrics.processing_errors}")

# 工具调用指标
print(f"工具选择准确率: {metrics.tool_selection_accuracy:.2%}")
print(f"参数准确率: {metrics.parameter_accuracy:.2%}")
print(f"执行成功率: {metrics.execution_success_rate:.2%}")
print(f"响应质量: {metrics.response_quality:.2%}")
print(f"综合得分: {metrics.overall_score:.2%}")

指标	描述
tool_selection_accuracy	模型正确选择工具的频率
parameter_accuracy	工具参数与预期值匹配的频率
execution_success_rate	有效且可执行的工具调用比例
response_quality	非工具相关响应的质量评分
overall_score	所有指标的加权组合

访问单个预测结果

results = evaluator.evaluate(dataset=eval_dataset)

# 遍历每个样本的评估结果
for pred in results.predictions:
    print(f"样本 {pred.sample_id}:")
    print(f"  查询: {pred.query}")
    print(f"  预期工具: {pred.expected_tool}")
    print(f"  预测工具: {pred.predicted_tool}")
    print(f"  工具选择是否正确: {pred.tool_selection_correct}")
    print(f"  参数是否正确: {pred.parameters_correct}")
    if pred.error:
        print(f"  错误: {pred.error}")

从 JSONL 文件进行评估

from deepfabric.evaluation import Evaluator, EvaluatorConfig, InferenceConfig

config = EvaluatorConfig(
    dataset_path="eval_dataset.jsonl",  # 直接从文件加载数据集
    inference_config=InferenceConfig(
        model_path="./my-model",
        backend="transformers",
    ),
    output_path="results.json",
)

evaluator = Evaluator(config)
results = evaluator.evaluate()  # 无需传入数据集参数

使用 Ollama 后端

from deepfabric.evaluation import Evaluator, EvaluatorConfig, InferenceConfig

config = EvaluatorConfig(
    inference_config=InferenceConfig(
        model_path="llama3.2:latest",  # Ollama 模型名称
        backend="ollama",
        temperature=0.1,
    ),
)

evaluator = Evaluator(config)
results = evaluator.evaluate(dataset=eval_dataset)

服务提供商

服务提供商	本地/云端	最适合场景
OpenAI	云端	高质量、复杂任务
Anthropic	云端	细致的推理能力
Google Gemini	云端	大规模应用时成本效益高
Ollama	本地	注重隐私、无限生成能力
OpenRouter	云端	灵活的模型选择

使用 Spin 进行工具追踪

DeepFabric 支持在数据集生成过程中真实执行工具，借助 Spin 框架实现。不同于模拟工具输出，工具会在隔离的 WebAssembly 沙盒中真正执行，从而生成真实的训练数据。

为什么真实执行很重要？

传统的合成数据生成器会模拟工具输出，这会导致生成不真实的训练数据：

# 模拟（存在问题）
代理：read_file("config.json")
结果：{"setting": "value"}  # LLM 幻觉出的内容

而通过集成 Spin，工具会基于真实状态执行：

# 真实执行（准确）
代理：read_file("config.json")
结果：FileNotFound  # 实际文件系统状态
代理：write_file("config.json", "{...}")
结果：成功写入 42 字节  # 真实操作

ReAct 式执行流程

DeepFabric 使用 ReAct（思考-行动-观察）循环来调用工具。代理会根据实际观察到的结果再决定下一步行动：

步骤 1：代理认为“应该检查配置文件是否存在”
        -> 调用 read_file("config.json")
        -> 观察到：FileNotFound

步骤 2：代理认为“配置文件不存在，需要创建它”
        -> 调用 write_file("config.json", 内容)
        -> 观察到：成功

这种方式生成的训练数据是基于真实观察做出决策，而非基于幻觉假设。

配置

在 YAML 配置中启用工具追踪：

generation:
  conversation:
    type: cot
    reasoning_style: agent

  tools:
    spin_endpoint: "http://localhost:3000"  # Spin 服务地址
    available:                              # 仅允许使用指定工具
      - read_file
      - write_file
      - list_files
    max_agent_steps: 5                      # 最大 ReAct 迭代次数

    # 可选：为场景设置初始状态
    scenario_seed:
      files:
        "config.json": '{"debug": true}'

内置 VFS 工具

DeepFabric 包含一个虚拟文件系统（VFS）组件，提供以下工具：

工具	描述
read_file	读取文件内容
write_file	写入文件内容
list_files	列出当前会话中的所有文件
delete_file	删除文件

每个会话都拥有独立的文件系统——更改不会在不同样本之间保留。

在本地运行 Spin

cd tools-sdk
spin build
spin up

Spin 服务默认运行在 http://localhost:3000。

添加自定义工具

你可以使用 Python、JavaScript、Go 或 Rust 编写自定义工具并扩展 DeepFabric。详细文档请参阅 tool-traces.md，内容包括：

• 创建自定义 Spin 组件
• 工具定义模式
• 多语言示例
• 容器化与部署

资源

• 文档
• 示例
• 工具追踪指南
• Discord
• 问题反馈

开发

git clone https://github.com/always-further/deepfabric
cd deepfabric
uv sync --all-extras
make test

数据分析

我们收集匿名使用数据以改进 DeepFabric。不会收集任何个人数据、提示或 API 密钥。

# 禁用数据分析
export ANONYMIZED_TELEMETRY=False

DeepFabric 快速上手指南

DeepFabric 是一个用于生成大语言模型（LLM）和智能体（Agent）训练数据的开源工具。它通过结合推理轨迹（Reasoning Traces）和工具调用模式，生成高质量、特定领域的合成数据集，帮助模型学习思考、规划、执行工具调用并遵循严格的结构化格式。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• Python: 版本 3.9 或更高
• Docker: 必须安装并运行，用于启动隔离的 WebAssembly 工具执行环境（Spin 服务）。
• API Key: 需要有效的 LLM 提供商 API Key（如 OpenAI）。

安装步骤

1. 安装 Python 包

使用 pip 安装 DeepFabric：

pip install deepfabric

提示：国内用户若下载缓慢，可使用清华源加速： pip install deepfabric -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 启动工具执行服务 (Docker)

DeepFabric 使用 mocked tool execution（模拟工具执行），需要运行一个 Spin 服务来处理文件读写等操作。请运行以下命令启动 Docker 容器：

docker run -d -p 3000:3000 ghcr.io/always-further/deepfabric/tools-sdk:latest

3. 配置环境变量

设置您的 LLM 提供商 API Key（以 OpenAI 为例）：

export OPENAI_API_KEY="your-api-key"

基本使用

DeepFabric 支持通过 CLI 命令行或 YAML 配置文件两种方式运行。以下是两种最快捷的上手方式。

方式一：CLI 快速生成（最简单）

直接使用命令行参数生成一个简单的主题图谱和训练样本。以下示例将生成关于"Python 编程基础”的数据集：

deepfabric generate \
  --topic-prompt "Python programming fundamentals" \
  --generation-system-prompt "You are a Python expert" \
  --mode graph \
  --depth 3 \
  --degree 3 \
  --num-samples 9 \
  --batch-size 3 \
  --provider openai \
  --model gpt-4o \
  --output-save-as dataset.jsonl

说明：

• 该命令会生成一个包含 27 个唯一节点的主题图。
• 最终生成 27 条训练样本并保存为 dataset.jsonl。
• --mode graph 确保主题覆盖的多样性，避免冗余。

方式二：使用 YAML 配置文件（推荐用于生产场景）

对于更复杂的场景（如定义具体工具、种子文件、详细系统提示词），建议使用 YAML 配置。

1. 创建名为 config.yaml 的文件，内容如下：

llm:
  provider: "openai"
  model: "gpt-4o"
  temperature: 0.7

topics:
  prompt: "Building production-ready REST APIs with Python"
  mode: tree
  depth: 3
  degree: 3
  save_as: "topics.jsonl"
  llm:
    model: "gpt-4o-mini"

generation:
  system_prompt: |
    You are an expert Python backend developer specializing in REST API design.
    Create practical, production-ready code examples with clear explanations.
    Include error handling, type hints, and follow PEP 8 conventions.
    Use the following tools to read, write, and list files in the virtual filesystem:
    - read_file
    - write_file
    - list_files

  instructions: |
    Focus on real-world scenarios developers encounter daily when building REST APIs with Python.
    Include both happy path and edge case handling.

  conversation:
    type: cot
    reasoning_style: agent

  tools:
    spin_endpoint: "http://localhost:3000"
    components:
      builtin:
        - read_file
        - write_file
        - list_files
    max_per_query: 3
    max_agent_steps: 5

  scenario_seed:
    files:
      "main.py": |
        def greet(name):
            return f"Hello, {name}!"

output:
  system_prompt: |
    You are a helpful Python programming assistant specialized in REST API development.
  include_system_message: true
  num_samples: 4
  batch_size: 3
  save_as: "api-dataset.jsonl"

2. 运行配置生成数据：

deepfabric generate config.yaml

后续步骤简述

生成 dataset.jsonl 后，您可以直接将其上传至 Hugging Face 或加载到主流训练框架中：

• 上传至 Hugging Face:

  deepfabric upload-hf dataset.jsonl --repo your-username/my-dataset
  

• 训练与评估: 生成的数据格式兼容 HuggingFace datasets 库，可直接配合 TRL, Unsloth, 或 Axolotl 进行微调。DeepFabric 还内置了 Evaluator 模块，可在训练后自动评估模型的工具选择准确率和参数准确率。