GEPA：基于反射式文本进化的 AI 系统优化框架完全指南

§1 学习目标

完成本文档后，你将能够：

• ✅ 理解 GEPA 的核心定位与设计理念
• ✅ 掌握 GEPA 的安装与基本使用方法
• ✅ 理解 GEPA 的反射式进化算法工作原理
• ✅ 使用 GEPA 优化提示词、系统配置和智能体架构
• ✅ 掌握 GEPA 与 DSPy、MLflow 等主流框架的集成方法
• ✅ 理解 Pareto 前沿与 Actionable Side Information 概念
• ✅ 使用 GEPA 适配器构建自定义优化系统

§2 项目概述

2.1 什么是 GEPA？

GEPA（Genetic-Pareto，GitHub 仓库）是一个用于优化任何文本参数系统的框架，支持提示词、代码、智能体架构、配置等任何文本内容的优化。

官方描述：

GEPA (Genetic-Pareto) is a framework for optimizing any system with textual parameters against any evaluation metric. Unlike RL or gradient-based methods that collapse execution traces into a single scalar reward, GEPA uses LLMs to read full execution traces — error messages, profiling data, reasoning logs — to diagnose why a candidate failed and propose targeted fixes. Through iterative reflection, mutation, and Pareto-aware selection, GEPA evolves high-performing variants with minimal evaluations.

核心哲学：如果你能测量它，你就能优化它。

2.2 核心数据

2.3 技术栈

2.4 核心特性

2.5 核心优势

§3 核心成果

3.1 性能对比

3.2 实际应用

3.3 生产使用

已在 50+ 生产环境中使用，包括 Shopify、Databricks、Dropbox、OpenAI、Pydantic、MLflow、Comet ML 等。

§4 工作原理

4.1 传统优化器的局限

传统优化器知道候选方案失败（that），但不知道为什么失败（why）。它们将执行轨迹压缩成单一标量奖励，无法提供具体的改进方向。

4.2 GEPA 的解决思路

GEPA 采用反射式进化方法，核心五步：

1. Select（选择）：从 Pareto 前沿中选择候选方案（在不同任务子集上表现出色的方案）

2. Execute（执行）：在小型批处理上执行，捕获完整执行轨迹

3. Reflect（反射）：LLM 读取轨迹（错误消息、性能分析器输出、推理日志）并诊断失败原因

4. Mutate（变异）：基于所有祖先累积的经验教训生成改进的候选方案

5. Accept（接受）：如果改进则添加到池中，更新 Pareto 前沿

4.3 Actionable Side Information (ASI)

核心概念：由评估器返回的诊断反馈，作为文本优化的梯度类比。

ASI 使得 GEPA 能够：

• 理解为什么候选方案失败
• 提供具体的改进建议
• 保留丰富的上下文信息

4.4 System-Aware Merge

GEPA 还支持系统感知合并，将两个在不同任务上表现出色的 Pareto 最优候选方案的优势结合起来。

§5 安装与部署

5.1 pip 安装

pip install gepa

5.2 从源码安装

pip install git+https://github.com/gepa-ai/gepa.git

5.3 依赖

GEPA 需要：

• Python 3.10+
• 一个 LLM 提供者（OpenAI、Anthropic、Google 等）

§6 快速开始

6.1 简单的提示词优化

import gepa

# 初始化数据集
trainset, valset, _ = gepa.examples.aime.init_dataset()

# 定义初始提示词
seed_prompt = {
    "system_prompt": (
        "You are a helpful assistant. Answer the question. "
        "Put your final answer in the format '### <answer>'"
    )
}

# 运行优化
result = gepa.optimize(
    seed_candidate=seed_prompt,
    trainset=trainset,
    valset=valset,
    task_lm="openai/gpt-4.1-mini",
    max_metric_calls=150,
    reflection_lm="openai/gpt-5",
)

print("Optimized prompt:", result.best_candidate['system_prompt'])

结果：GPT-4.1 Mini 在 AIME 2025 上从 46.6% 提升至 56.6%（+10 个百分点）。

6.2 与 DSPy 集成（推荐用于 AI 流水线）

import dspy

# 创建 GEPA 优化器
optimizer = dspy.GEPA(
    metric=your_metric,
    max_metric_calls=150,
    reflection_lm="openai/gpt-5",
)

# 编译优化后的程序
optimized_program = optimizer.compile(
    student=MyProgram(),
    trainset=trainset,
    valset=valset,
)

6.3 optimize_anything：超越提示词

optimize_anything API 可以优化任何文本产物，不仅仅是提示词：

from gepa.optimize_anything import optimize_anything, GEPAConfig, EngineConfig

def evaluate(candidate: str) -> float:
    result = run_my_system(candidate)
    # 记录可操作的关键信息
    oa.log(f"Output: {result.output}")
    oa.log(f"Error: {result.error}")  # 反馈到反射中
    return result.score

result = optimize_anything(
    seed_candidate="<your initial artifact>",
    evaluator=evaluate,
    objective="Describe what you want to optimize for.",
    config=GEPAConfig(
        engine=EngineConfig(max_metric_calls=100)
    ),
)

§7 内置适配器

7.1 适配器概览

7.2 DefaultAdapter

用于单轮 LLM 任务的系统提示词优化：

from gepa.adapters.default_adapter import DefaultAdapter

adapter = DefaultAdapter()

7.3 DSPy Full Program Adapter

进化整个 DSPy 程序，包括签名、模块和控制流：

from gepa.adapters.dspy_full_program_adapter import DSPyFullProgramAdapter

adapter = DSPyFullProgramAdapter()

效果：MATH 准确率从 67% 提升至 93%。

7.4 Generic RAG Adapter

向量存储无关的 RAG 优化：

from gepa.adapters.generic_rag_adapter import GenericRAGAdapter

adapter = GenericRAGAdapter()

支持：ChromaDB、Weaviate、Qdrant、Pinecone 等。

7.5 MCP Adapter

优化 Model Context Protocol (MCP) 工具描述：

from gepa.adapters.mcp_adapter import MCPAdapter

adapter = MCPAdapter()

7.6 自定义适配器

通过实现 evaluate 和 make_reflective_dataset 方法构建自己的适配器：

from gepa.core.adapter import GEPAAdapter

class MyAdapter(GEPAAdapter):
    def evaluate(self, candidate: dict) -> float:
        # 实现评估逻辑
        return score

    def make_reflective_dataset(self, candidate: dict) -> ReflectiveDataset:
        # 实现反射数据集创建
        return dataset

§8 框架集成

8.1 DSPy 集成

import dspy

optimizer = dspy.GEPA(
    metric=your_metric,
    max_metric_calls=150,
    reflection_lm="openai/gpt-5",
)

optimized_program = optimizer.compile(
    student=MyProgram(),
    trainset=trainset,
    valset=valset,
)

8.2 MLflow 集成

import mlflow

# mlflow.genai.optimize_prompts() API

8.3 Comet ML Opik 集成

Opik Agent Optimizer 的核心优化算法。

8.4 Pydantic AI 集成

用于 Pydantic AI 的提示词优化。

8.5 OpenAI Cookbook 集成

构建自进化智能体。

8.6 HuggingFace Cookbook 集成

DSPy + GEPA 提示词优化指南。

8.7 Google ADK 集成

优化 Google Agent Development Kit 智能体。

§9 适用场景

9.1 GEPA 擅长的场景

9.2 GEPA 与 RL 的互补

使用 GEPA 进行快速初始优化，然后应用 RL/微调获得额外收益。

§10 项目结构

10.1 目录结构

gepa/
├── src/gepa/           # 核心源代码
│   ├── core/           # 核心组件
│   │   └── adapter.py  # GEPAAdapter 接口
│   ├── adapters/       # 内置适配器
│   │   ├── default_adapter/
│   │   ├── dspy_full_program_adapter/
│   │   ├── generic_rag_adapter/
│   │   ├── mcp_adapter/
│   │   ├── terminal_bench_adapter/
│   │   └── anymaths_adapter/
│   └── examples/      # 示例
├── tests/              # 测试
├── docs/               # 文档
├── examples/           # 示例
├── assets/             # 资源
├── pyproject.toml       # Python 项目配置
└── README.md          # 项目文档

10.2 核心模块

§11 最佳实践

11.1 优化策略

11.2 Actionable Side Information

确保评估器返回可操作的诊断反馈：

• 具体的错误信息
• 性能分析数据
• 推理日志

11.3 并行优化

config = GEPAConfig(
    engine=EngineConfig(
        max_metric_calls=100,
        parallel_evaluations=4  # 并行评估
    )
)

§12 常见问题

Q1：GEPA 与 RL 有何区别？

Q2：GEPA 可以优化哪些内容？

任何文本内容：提示词、代码、智能体架构、配置、SVG 等。

Q3：需要什么数据来开始？

只需 3 个样本即可开始优化。

Q4：GEPA 支持哪些 LLM？

通过 API 支持任何 LLM：OpenAI、Anthropic、Google、Meta 等。

Q5：如何构建自定义适配器？

实现 GEPAAdapter 接口的 evaluate 和 make_reflective_dataset 方法。

§13 总结

13.1 核心优势

13.2 适用对象

13.3 项目信息

13.4 相关链接

§14 附录：术语表

文档版本 1.0 | 撰写日期：2026-04-01 | 基于 GEPA (3.1k Stars) | 性能数据来源：官方基准测试