DSPy — 编程式 Prompt 自动优化框架

GitHub: stanfordnlp/dspy
Stars: 35,000+ | Language: Python (99.4%) | License: MIT
官网: dspy.ai | 最新版本: v3.2.1（2026 年 5 月）

项目速览

DSPy（Declarative Self-improving Python）是由斯坦福大学 NLP 组推出的编程式 Prompt 自动优化框架。它的核心理念是”编程而非提示词”（Programming—not prompting）：开发者用 Python 代码定义 AI 系统的逻辑和约束，DSPy 的编译器（称为 Teleprompter/Optimizer）自动优化底层的 Prompt 指令和 Few-shot 示例，甚至可以对模型权重进行微调。

传统 Prompt 工程的痛点在于脆弱性——换一个模型、改一个版本，精心手写的 Prompt 就可能失效。DSPy 的解决思路是提升抽象层级：你不再直接编写 Prompt 字符串，而是定义输入/输出规范（Signature）、构建模块化程序（Module），然后用指标驱动的优化器自动编译出最优 Prompt。当底层模型切换时，只需重新编译，无需手动改写任何 Prompt。

DSPy 由 Omar Khattab、Arnav Gudibande 等研究人员创建，其学术论文发表于 ICLR 2024 并获得 Oral 荣誉。截至 2026 年 6 月，项目在 GitHub 上已获得 35,000+ Star、109 个 Release，社区活跃且持续增长。OpenAI、Anthropic 等头部 AI 公司均在使用 DSPy 进行内部 Prompt 优化。

功能概述

Signature — 抽象 Prompt 为输入/输出规范

Signature 是 DSPy 最核心的抽象。它将传统 Prompt 中的”输入字段”和”期望输出字段”声明为类似函数签名的结构，通过 Python 的类定义或简写字符串来表达。Signature 自动包含了字段描述、类型约束等元信息，编译器可以据此自动生成和优化 Prompt。

类定义式 Signature：

import dspy

class BasicQA(dspy.Signature):
    """Answer questions with short factoid answers."""

    question: str = dspy.InputField()
    answer: str = dspy.OutputField(desc="often between 1 and 5 words")

简写字符串式（用于简单场景）：

qa = dspy.Predict('question: str -> response: str')

这种声明式定义让模型调用的”接口”变得像函数签名一样清晰。Docstring 和 desc 参数作为语义信息参与编译优化，要比在 Prompt 模板里手动调整措辞可靠得多。

Module — 可组合的 AI 组件

Module 是 DSPy 的组件化编程单元，类似于 PyTorch 的 nn.Module。每个 Module 包含一个或多个 Predictor（如 dspy.ChainOfThought、dspy.Predict），在 forward() 方法中定义它们的调用和组合逻辑。

class RAG(dspy.Module):
    def __init__(self):
        self.respond = dspy.ChainOfThought('context, question -> response')

    def forward(self, question):
        context = search(question).passages
        return self.respond(context=context, question=question)

Module 支持嵌套组合，你可以像搭积木一样构建复杂的 Agent 管道：一个 Module 的输出可以成为另一个 Module 的输入，DSPy 的编译器会追踪整个调用图并在每个节点应用优化。

Optimizer/Teleprompter — 自动编译优化

DSPy 提供多种优化器（Teleprompter），它们基于训练数据自动改进程序的 Prompt 和 Few-shot 示例。核心优化器包括：

**BootstrapFewShot**：通过自举（bootstrap）方式生成高质量的 Few-shot 示例，基于正确执行轨迹自动选择最有效的示例组合
**BootstrapFewShotWithRandomSearch**：在 BootstrapFewShot 基础上加入随机搜索，跨多个候选程序探索最佳 Few-shot 配置
**MIPROv2**：第二代多交互式 Prompt 优化器，支持 auto="light"、"medium" 或 "heavy" 三种优化强度，同时优化指令和 Few-shot 示例
**COPRO**：基于 LLM 生成新 Prompt 候选，逐层深度搜索最优指令
**KNNFewShot**：根据输入查询的语义嵌入，动态检索最相似的 Few-shot 示例
**BootstrapFinetune**：结合 Few-shot 自举和模型微调，在训练数据上直接优化模型权重
**LabeledFewShot**：简单地从训练集中选择 k 个标注示例作为 Few-shot 提示

以最常用的 MIPROv2 为例：

from dspy.teleprompt import MIPROv2

teleprompter = MIPROv2(metric=my_metric, auto="medium", num_threads=24)
optimized_rag = teleprompter.compile(
    RAG(), trainset=trainset,
    max_bootstrapped_demos=2, max_labeled_demos=2
)
optimized_rag.save("optimized_rag.json")

检索增强生成集成

DSPy 内置了多种检索器，可以直接与 Module 组合构建 RAG 系统：

# 使用本地 Embedding 检索
embedder = dspy.Embedder('openai/text-embedding-3-small', dimensions=512)
search = dspy.retrievers.Embeddings(embedder=embedder, corpus=corpus, k=5)

# 或使用 ColBERTv2 服务端检索
colbertv2 = dspy.ColBERTv2(url='http://20.102.90.50:2017/wiki17_abstracts')
dspy.configure(rm=colbertv2)
retriever = dspy.Retrieve(k=3)

评估与指标

DSPy 提供了完整的评估框架 dspy.Evaluate，支持多线程批量评估、进度显示和结果表格展示：

from dspy.evaluate import Evaluate, SemanticF1

metric = SemanticF1(decompositional=True)
evaluate = dspy.Evaluate(
    devset=devset, metric=metric, num_threads=24,
    display_progress=True, display_table=2
)
evaluate(rag_program)

内置指标包括精确匹配、SemanticF1 等，也可以自定义指标函数。LLM-as-Judge 模式同样受支持：

class FactJudge(dspy.Signature):
    """Judge if the answer is factually correct based on the context."""
    context = dspy.InputField(desc="Context for the prediction")
    question = dspy.InputField(desc="Question to be answered")
    answer = dspy.InputField(desc="Answer for the question")
    factually_correct: bool = dspy.OutputField()

judge = dspy.ChainOfThought(FactJudge)

def factuality_metric(example, pred):
    factual = judge(context=example.context, question=example.question, answer=pred.answer)
    return factual.factually_correct

高级控制功能

**dspy.ReAct**：内置 ReAct Agent 循环，支持工具调用和多步推理
**dspy.ProgramOfThought**：代码辅助推理，让模型在生成答案前先编写思维程序
**dspy.Parallel**：多线程并行调用，提升批处理效率
**dspy.asyncify**：将同步 Module 转为异步执行
**dspy.BestOfN / dspy.Refine**：N 次采样后根据奖励函数选择最优结果
**dspy.CodeAct**：让 LM 通过 Python 函数调用执行计算任务

适用场景

RAG 系统开发：用 Module 组合检索器和生成器，用 MIPROv2 自动优化 Prompt，比手写 LangChain 链获得更高的稳定性和可维护性
分类与信息抽取：定义输入文本和期望标签的 Signature，BootstrapFewShot 自动从少量标注数据中学习最优 Prompt
数学推理：结合 ProgramOfThought 和 GSM8K 风格指标，自动优化数学题求解 Pipeline
多模型适配：从 GPT-4o 切换到 Claude Opus 或开源模型时，重新编译即可，无需手动改写 Prompt
Prompt 版本管理：编译后的程序可序列化为 JSON 文件，实现 Prompt 的版本控制、A/B 测试和回滚
Agent 循环优化：用 ReAct Module 定义 Agent 行为，通过 MIPROv2 自动优化 Agent 指令和工具调用策略

快速上手

安装

pip install dspy

最小示例

import dspy

# 1. 配置语言模型
lm = dspy.LM('openai/gpt-4o-mini')
dspy.configure(lm=lm)

# 2. 定义任务签名
class BasicQA(dspy.Signature):
    """Answer questions with short factoid answers."""
    question: str = dspy.InputField()
    answer: str = dspy.OutputField(desc="often between 1 and 5 words")

# 3. 创建 ChainOfThought 预测器
generate_answer = dspy.ChainOfThought(BasicQA)

# 4. 调用
pred = generate_answer(question='What is the color of the sky?')
print(pred.answer)

核心 API 速查

组件	用途	示例
`dspy.LM(model_string)`	配置语言模型	`dspy.LM('openai/gpt-4o-mini')`
`dspy.configure(lm=lm)`	全局设置 LM	`dspy.configure(lm=lm)`
`dspy.Signature`	定义输入/输出规范	`class QA(dspy.Signature): ...`
`dspy.ChainOfThought`	CoT 预测器	`dspy.ChainOfThought(QA)`
`dspy.Module`	可组合模块	`class RAG(dspy.Module): ...`
`dspy.Embedder`	文本嵌入	`dspy.Embedder('openai/text-embedding-3-small', dimensions=512)`
`dspy.retrievers.Embeddings`	向量检索	`dspy.retrievers.Embeddings(embedder=embedder, corpus=corpus, k=5)`
`dspy.ReAct`	Agent 循环	`dspy.ReAct(QA)`
`dspy.Evaluate`	评估框架	`dspy.Evaluate(devset=devset, metric=metric, ...)`
`MIPROv2`	Prompt 优化器	`MIPROv2(metric=metric, auto="medium")`

源码架构

DSPy 的仓库组织简洁清晰，核心代码全部位于 dspy/ 目录下：

dspy/
├── adapters/          # 模型适配器（Chat/Completion 格式转换）
├── cli/               # 命令行工具
├── clients/           # LM 客户端（OpenAI、Anthropic 等）
├── evaluate/          # 评估框架（Evaluate、SemanticF1 等指标）
├── functional/        # 函数式 DSL 编程接口
├── primitives/        # 基础原语（Predict、Example、Assertion）
├── propose/           # 自动生成 Prompt 候选
├── retrieve/          # 检索模块（Embeddings、ColBERTv2、Qdrant 等）
├── teleprompt/        # 优化器（MIPROv2、BootstrapFewShot、COPRO 等）
│   └── ensemble/      # 集成学习优化
├── tools/             # 工具调用
└── utils/             # 工具函数

核心设计模式：

Lazy Compilation：定义 Module 时不立即生成 Prompt，调用 compile() 时才进行优化
Type-Driven Prompt Generation：基于 Python 类型注解自动生成 Prompt 指令
Optimizer Pipeline：train -> bootstrap -> optimize -> save 的标准化编译流程
Adapter Pattern：通过 Adapter 抽象不同 LLM 提供商的 Chat/Completion 格式差异

实操 Demo

以下演示一个完整的 RAG Pipeline 构建与自动优化流程。

步骤 1：环境准备

import dspy
import orjson
from dspy.utils import download
from dspy.evaluate import SemanticF1

# 配置语言模型
lm = dspy.LM('openai/gpt-4o-mini')
dspy.configure(lm=lm)

# 下载示例数据集
download("https://huggingface.co/dspy/cache/resolve/main/ragqa_arena_tech_examples.jsonl")

with open("ragqa_arena_tech_examples.jsonl") as f:
    data = [orjson.loads(line) for line in f]

data = [dspy.Example(**d).with_inputs('question') for d in data]

import random
random.Random(0).shuffle(data)
trainset, devset, testset = data[:200], data[200:500], data[500:1000]

步骤 2：构建检索器

max_characters = 6000
topk_docs_to_retrieve = 5

with open("ragqa_arena_tech_corpus.jsonl") as f:
    corpus = [orjson.loads(line)['text'][:max_characters] for line in f]

embedder = dspy.Embedder('openai/text-embedding-3-small', dimensions=512)
search = dspy.retrievers.Embeddings(
    embedder=embedder, corpus=corpus, k=topk_docs_to_retrieve
)

步骤 3：定义 RAG Module

class RAG(dspy.Module):
    def __init__(self):
        self.respond = dspy.ChainOfThought('context, question -> response')

    def forward(self, question):
        context = search(question).passages
        return self.respond(context=context, question=question)

步骤 4：评估基线程序

metric = SemanticF1(decompositional=True)

evaluate = dspy.Evaluate(
    devset=devset, metric=metric, num_threads=24,
    display_progress=True, display_table=2
)

baseline_score = evaluate(RAG())
print(f"Baseline score on devset: {baseline_score}")

步骤 5：使用 MIPROv2 自动优化

from dspy.teleprompt import MIPROv2

# 中等强度优化
tp = dspy.MIPROv2(metric=metric, auto="medium", num_threads=24)

optimized_rag = tp.compile(
    RAG(), trainset=trainset,
    max_bootstrapped_demos=2, max_labeled_demos=2
)

# 评估优化后程序
optimized_score = evaluate(optimized_rag)
print(f"Optimized score on devset: {optimized_score}")
print(f"Improvement: {optimized_score - baseline_score:.2%}")

# 保存优化结果
optimized_rag.save("optimized_rag.json")

步骤 6：检查编译器生成的 Prompt

# 查看优化后的 Prompt 结构
dspy.inspect_history(n=1)

步骤 7：加载并复用

loaded_rag = RAG()
loaded_rag.load("optimized_rag.json")
result = loaded_rag(question="What is Docker?")
print(result.response)

步骤 8：切换模型重新编译

# 切换到 Claude，只需更换 LM 并重新编译
new_lm = dspy.LM('anthropic/claude-sonnet-4-20250514')
dspy.configure(lm=new_lm)

tp_claude = dspy.MIPROv2(metric=metric, auto="medium", num_threads=24)
rag_for_claude = tp_claude.compile(
    RAG(), trainset=trainset,
    max_bootstrapped_demos=2, max_labeled_demos=2
)
rag_for_claude.save("rag_for_claude.json")

维度	DSPy	Guidance	LangChain Prompt Templates
核心理念	编程式自动优化 Prompt	受控生成，约束输出格式	模板化 Prompt 管理
优化能力	自动编译优化指令 + Few-shot + 权重	无自动优化，手动编写模板	无优化，纯模板替换
输出约束	通过 OutputField 描述约束	强约束：regex、JSON Schema、CFG	无内置约束，依赖 Output Parser
模型切换	重新编译自动适配	模板与模型无关，但需手动调优	需手动调整模板内容
学习曲线	中等，需理解 Signature/Module/Optimizer	低，Handlebars 风格模板直观	低，Python 字符串模板
社区生态	学术界为主，35k Star，ICLR 2024 Oral	21.5k Star，工业界使用较多	LangChain 生态，139k Star
适用阶段	开发 + 优化阶段	推理部署阶段	全生命周期

参考资源

官方文档： https://dspy.ai
GitHub 仓库： https://github.com/stanfordnlp/dspy
学术论文： “DSPy: Compiling Declarative Language Model Calls into Self-Improving Pipelines” (ICLR 2024 Oral)
教程： dspy.ai/tutorials/rag/ — 官方 RAG 教程，包含完整的端到端示例
速查表： dspy.ai/cheatsheet/ — API 速查手册
Hugging Face 模型： 支持 OpenAI、Anthropic、Google、开源模型（通过 HF 接口）等主流 LLM 提供商