DSPy 完全指南：从入门到精通
1. DSPy 概述
DSPy 是一个面向编程而非提示工程的语言模型框架，它提供了构建模块化 AI 系统并自动优化其提示词和权重的能力。DSPy 的完整名称是 Declarative Self-improving Python（声明式自改进 Python），由 Stanford NLP 团队从 2022 年开始开发，已发展成为构建和优化语言模型程序的强大工具。
DSPy 的核心理念是将 AI 系统设计与具体的语言模型或提示策略解耦。它提供了优化算法，可以自动将 AI 程序编译成有效的提示和权重，无论您是构建简单的分类器、复杂的 RAG 管道，还是 Agent 循环系统。
与传统的 Agent 或 Workflow 框架不同，DSPy 代表了一种范式转变——从手工制作提示词和工作流，转向编写可优化的程序结构。它特别适合需要在多个模型间迁移、需要系统性能优化、或者构建复杂多阶段 AI 系统的场景。
1.1 核心优势
DSPy 框架为开发者提供了以下核心优势，使其成为构建 AI 系统的理想选择：
- 声明式编程：用 Python 代码描述 AI 行为，而非手动编写提示词
- 自动优化：提供多种优化器来自动改进提示和模型权重
- 模块化设计：可组合的模块使 AI 系统更可靠、可维护和可移植
- 跨模型兼容：轻松切换不同的语言模型和推理策略
2. 快速开始
2.1 安装与配置
首先安装 DSPy：
pip install -U dspy然后配置您的语言模型。DSPy 支持多种提供商，以下是几种常见的配置方式。
使用 OpenAI：
import dspy
lm = dspy.LM("openai/gpt-4o-mini", api_key="YOUR_OPENAI_API_KEY")
dspy.configure(lm=lm)使用本地模型（Ollama）：
lm = dspy.LM("ollama_chat/llama3.2:1b", api_base="http://localhost:11434", api_key="")
dspy.configure(lm=lm)DSPy 通过 dspy.LM 提供统一的接口，支持 OpenAI、Anthropic、Databricks、Gemini 等多个提供商，以及任何 OpenAI 兼容的端点。这个统一接口不仅简化了模型切换的复杂度，还内置了缓存和使用追踪功能。
2.2 核心概念
2.2.1 声明式签名（Signatures）
DSPy 使用声明式的输入/输出行为规范，而不是手工编写提示词。签名定义了模块需要做什么，而不是如何去做。这种抽象方式将任务的意图与具体实现分离，使得代码更加清晰和可维护。
例如，一个简单的问答任务可以表示为 "question -> answer"，而一个基于上下文的问答任务则可以表示为 "context, question -> response"。这种方式使任务定义更加清晰和模块化，开发者无需关心底层的提示词构造细节。
2.2.2 模块化编程组件（Modules）
DSPy 提供了一系列可组合的构建块，每个模块抽象了一种提示技术，这些模块可以像乐高积木一样组合使用：
dspy.Predict：基础预测器，用于简单的输入输出映射dspy.ChainOfThought：链式思考推理，引导模型进行逐步推理dspy.ReAct：可使用工具的 Agent，支持推理和行动的循环dspy.ProgramOfThought：代码生成与执行，让模型通过代码解决问题dspy.Retrieve：检索模块，用于检索相关文档
这些模块的设计遵循了统一的接口规范，使得它们可以无缝替换和组合，从而构建复杂的 AI 系统。
2.3 基础模块示例
下面介绍三种最常用的基础模块及其使用方式。
2.3.1 简单预测（dspy.Predict）
from typing import Literal
class Classify(dspy.Signature):
"""Classify sentiment of a given sentence."""
sentence: str = dspy.InputField()
sentiment: Literal["positive", "negative", "neutral"] = dspy.OutputField()
confidence: float = dspy.OutputField()
classify = dspy.Predict(Classify)
result = classify(sentence="This book was super fun to read!")这个示例展示了如何使用 dspy.Predict 进行简单的情感分类任务。
2.3.2 思维链推理（dspy.ChainOfThought）
math = dspy.ChainOfThought("question -> answer: float")
result = math(question="Two dice are tossed. What is the probability that the sum equals two?")思维链推理能够生成中间推理步骤，提高复杂问题的解决能力。
2.3.3 ReAct Agent
def search_wikipedia(query: str):
results = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")(query, k=3)
return [x["text"] for x in results]
react = dspy.ReAct("question -> answer: float", tools=[search_wikipedia])
pred = react(question="What is 9362158 divided by the year of birth of David Gregory?")ReAct 模式结合了推理（Reasoning）和行动（Acting），适合需要工具调用的复杂任务。
3. 构建多阶段系统
3.1 自定义模块
您可以通过继承 dspy.Module 并实现 forward 方法来创建自定义模块。自定义模块允许您将多个基础模块组合成复杂的处理流程：
class DraftArticle(dspy.Module):
def __init__(self):
self.build_outline = dspy.ChainOfThought(Outline)
self.draft_section = dspy.ChainOfThought(DraftSection)
def forward(self, topic):
outline = self.build_outline(topic=topic)
sections = []
for heading, subheadings in outline.section_subheadings.items():
section = self.draft_section(
topic=outline.title,
section_heading=f"## {heading}",
section_subheadings=subheadings
)
sections.append(section.content)
return dspy.Prediction(title=outline.title, sections=sections)这个示例展示了如何构建一个文章起草系统，它首先生成大纲，然后逐节生成内容。
3.2 RAG 系统示例
检索增强生成（RAG）是 DSPy 的典型应用场景。下面是一个简单的 RAG 实现：
class RAG(dspy.Module):
def __init__(self, num_docs=5):
self.num_docs = num_docs
self.respond = dspy.ChainOfThought("context, question -> response")
def forward(self, question):
context = search(question, k=self.num_docs)
return self.respond(context=context, question=question)这个 RAG 系统先检索相关文档，然后基于检索到的上下文回答问题。
4. 优化器系统
这是 DSPy 最独特和强大的功能。框架提供了多种优化器来自动改进系统性能，无需人工调整提示词。
4.1 优化器工作原理
所有 DSPy 优化器都实现 compile() 方法，该方法接收以下参数：
student：要优化的 DSPy 程序trainset：训练样本集metric：评估函数（分数越高越好）
这些优化器可以根据给定的训练数据和评估指标，自动搜索最佳的指令、示例组合或权重更新。不同的优化器采用不同的策略来提升性能，下面介绍几种主流的优化器。
4.2 MIPROv2：多阶段指令和演示优化
MIPROv2 是目前最先进的优化器，通过贝叶斯优化联合优化指令和少样本示例，在搜索空间中智能探索最优配置。它支持自动配置的轻量、中量和重量级优化：
from dspy.teleprompt import MIPROv2
tp = MIPROv2(metric=dspy.evaluate.answer_exact_match, auto="light", num_threads=24)
optimized_react = tp.compile(react, trainset=trainset)MIPROv2 通过以下三个阶段工作：
- 引导阶段：收集高质量的输入/输出轨迹
- 指令提案阶段：为每个模块生成候选指令
- 离散搜索阶段：优化指令和示例的组合
使用 dspy.MIPROv2 可以将 ReAct Agent 的准确率从 24% 提升到 51%，完全通过自动优化实现。典型的优化运行通常花费约 2 美元和 20 分钟时间。
4.3 BootstrapFewShot：少样本学习
BootstrapFewShot 优化器自动生成高质量示例，从训练数据中学习最有效的演示样本：
from dspy.teleprompt import BootstrapFewShot
optimizer = BootstrapFewShot(
metric=your_metric,
max_bootstrapped_demos=4,
max_labeled_demos=16
)
optimized_program = optimizer.compile(student=program, trainset=trainset)这种方法特别适合需要少量示例就能提升性能的场景。
4.4 BootstrapFinetune：权重微调
BootstrapFinetune 优化器能够构建数据集并微调模型权重，实现更深层次的模型优化：
from dspy.teleprompt import BootstrapFinetune
optimizer = BootstrapFinetune(metric=your_metric, num_threads=24)
optimized = optimizer.compile(classify, trainset=trainset)权重微调能够深度定制模型行为，适用于对性能要求较高的场景。
4.5 其他优化器
DSPy 还提供了多种专门用途的优化器：
- COPRO：通过坐标上升优化指令
- GEPA：使用反思式提示进化，让系统通过反思自身表现来改进
- SIMBA：随机内省小批量上升
- KNNFewShot：基于相似度的少样本学习
4.6 优化器组合策略
DSPy 优化器可以组合使用以获得更好的结果。例如，您可以先运行 MIPROv2 优化提示，然后使用其输出作为 BootstrapFinetune 的输入进行权重微调，这种组合策略往往能够取得最佳效果。
5. 高级功能与技巧
5.1 评估系统
使用 dspy.Evaluate 可以系统化地评估程序性能：
from dspy.evaluate import Evaluate
evaluator = Evaluate(
devset=devset,
metric=your_metric,
num_threads=24,
display_progress=True
)
score = evaluator(your_program)评估系统支持多线程并行评估，能够快速获得程序的性能指标。
5.2 自定义指标
DSPy 支持灵活的自定义指标定义方式，以下是两种常见的方法。
5.2.1 函数式指标
函数式指标直接通过函数定义评估逻辑：
def gsm8k_metric(gold, pred, trace=None) -> int:
return int(parse_integer_answer(str(gold.answer))) == int(parse_integer_answer(str(pred.answer)))5.2.2 LLM 作为评判者
对于难以用规则定义的指标，可以使用 LLM 作为评判者：
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):
return judge(context=example.context, question=example.question, answer=pred.answer).factually_correct这种方法特别适合需要主观判断的评估场景，如事实准确性、连贯性等。
5.3 输出优化技术
5.3.1 BestOfN 策略
BestOfN 策略运行模块 N 次并返回最佳结果：
qa = dspy.ChainOfThought("question -> answer")
def one_word_answer(args, pred):
return 1.0 if len(pred.answer) == 1 else 0.0
best_of_3 = dspy.BestOfN(module=qa, N=3, reward_fn=one_word_answer, threshold=1.0)5.3.2 Refine 迭代优化
Refine 提供带反馈的迭代优化机制：
refine = dspy.Refine(module=qa, N=3, reward_fn=one_word_answer, threshold=1.0)5.4 实用工具集
DSPy 提供了丰富的实用工具来增强开发体验：
- 缓存管理：DSPy 自动缓存 LM 调用，避免重复请求
- 流式输出：使用
dspy.streamify实现流式响应 - 异步支持：使用
dspy.asyncify提升并发性能 - 使用追踪：跟踪 token 使用情况，优化成本
- 并行执行：使用
dspy.Parallel实现并行处理
5.5 模型保存与加载
优化后的程序可以持久化保存，便于部署和复用：
# 保存
optimized_program.save('./v1.json')
# 加载
loaded_program = YourProgramClass()
loaded_program.load(path='./v1.json')这使得在不同环境中部署和测试变得非常便捷。
6. 与传统框架的核心区别
6.1 编程范式 vs 提示工程
DSPy 的核心理念是"编程而非提示"。传统框架要求开发者手工编写和调整提示词字符串，这是一个耗时且需要大量经验的过程。而 DSPy 让你编写结构化的 Python 代码，然后由编译器自动生成优化的提示。这种方式不仅提高了开发效率，还使得代码更加可维护和可测试。
6.2 自动优化 vs 手工调整
普通框架依赖人工迭代调整提示词或工作流，这个过程往往需要反复试验和大量的领域知识。DSPy 提供算法化的优化过程：给定训练数据和评估指标，优化器会自动搜索最佳的指令、示例组合或权重更新。这种方法不仅更加科学和系统化，而且可以发现人类可能忽略的优化机会。
6.3 参数化的提示 vs 静态字符串
DSPy 将提示和模型权重视为可学习的参数，而不是固定的字符串。这个设计理念使得系统可以在不同模型、不同任务上迁移和重新优化。当你切换到一个新的语言模型时，DSPy 可以自动调整提示策略，而不需要手工重写所有提示词。
6.4 声明式 vs 命令式
传统框架通常混淆了接口（"LM 应该做什么"）和实现（"如何告诉 LM 去做"）。DSPy 将二者分离：签名定义接口，优化器推断或学习实现。这种关注点分离使得系统更加灵活和可扩展，开发者可以专注于定义问题本身，而不是纠结于如何措辞提示词。
6.5 系统性优化 vs 局部调整
DSPy 的优化器可以同时优化多阶段流程中的所有模块，而不仅仅是调整单个组件。这种端到端的优化能力在复杂系统中特别有价值，因为各个组件之间往往存在相互依赖和协同效应。通过全局优化，DSPy 可以发现局部调整无法达到的性能提升。
7. 学习路径建议
根据官方教程和最佳实践，我们为不同水平的学习者规划了系统的学习路径，从基础到进阶逐步深入。
7.1 初级阶段：构建 AI 程序
这个阶段的学习目标是掌握 DSPy 的基本使用方法和常见应用场景，建议按以下顺序学习：
- RAG 系统：学习检索增强生成的基本原理和实现
- 对话历史管理：掌握如何构建对话式应用
- 分类任务：实践文本分类和情感分析
- 实体提取：学习结构化信息提取技术
7.2 中级阶段：优化 AI 程序
在熟悉基础使用后，可以学习如何通过优化器提升 AI 程序的性能：
- 数学推理优化：使用优化器提升推理能力
- 分类微调：通过微调显著提升分类性能
- 高级工具使用：学习优化工具调用能力
- Agent 微调：训练更智能的 Agent 系统
7.3 高级阶段：核心开发
这个阶段需要深入理解 DSPy 的内部机制，并能够扩展框架功能：
- 自定义模块开发：构建符合特定需求的 DSPy 组件
- 生产部署：掌握生产环境的最佳实践和监控方案
- GEPA 优化：学习反思式提示进化技术
- 性能调优：深入掌握缓存、流式和异步优化技术
8. 应用场景与价值
DSPy 框架的优化能力使得开发者可以专注于系统架构设计，而将提示工程的细节交给算法来处理。它特别适合以下场景：
- 多模型迁移场景：需要在不同语言模型之间切换，但希望保持代码一致性
- 性能敏感应用：需要系统性能优化，追求更高的准确率和效率
- 复杂多阶段系统：构建包含多个推理步骤的复杂 AI 系统
- 快速原型开发：希望快速验证想法，避免陷入提示词调优的细节中
通过将提示工程从艺术转变为科学，DSPy 为构建可靠、高效的 AI 系统提供了新的可能性。
9. 总结与展望
DSPy 代表了 AI 系统开发的新范式，它将提示工程从艺术转变为科学，使开发者可以像编写普通程序一样编写 AI 系统，然后通过优化器自动生成和优化底层的提示和权重。这使得 AI 系统更加可靠、可维护，并且能够随着新模型和优化技术的出现而不断改进。
通过本文的学习，您应该已经掌握了 DSPy 的核心概念、基本使用方法、优化技巧和高级功能。接下来建议您：
- 选择适合的学习路径：根据自己的技能水平选择初级、中级或高级学习路径
- 动手实践项目：通过实际项目来深入理解和应用 DSPy 的各项功能
- 参与社区交流：关注 DSPy 社区动态，学习最佳实践
- 持续优化迭代：不断尝试不同的优化器和策略，提升系统性能