dspy

DSPy 专家技能

DSPy 是一种提示词程序编译器，而不是链式或 RAG 框架。你可以编写带类型签名的 Python 程序，DSPy 会自动优化提示词。

⚠️ DSPy 不是链式框架。 它不使用 prompt | model | parser，也没有 LCEL。DSPy 作用于不同的层级：你用 Python 控制流和类型签名定义程序，然后由编译器针对某项指标优化提示词。如果你期待的是 LangChain 风格的组合方式，那么 DSPy 就不是你要找的工具。

可以把它看作适用于 LM 的 PyTorch——你定义架构，编译器调整权重（提示词）。

核心范式

请先阅读这一部分。这是理解 DSPy 最重要的内容。

import dspy

# 1. Configure the LM
lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)

# 2. Define a signature (input/output schema)
class QASignature(dspy.Signature):
    """Answer questions concisely."""
    question: str = dspy.InputField()
    answer: str = dspy.OutputField()

# 3. Build a program using modules
qa = dspy.ChainOfThought(QASignature)

# 4. Compile against a metric
optimizer = dspy.MIPROv2(metric=dspy.answer_exact_match)
compiled_qa = optimizer.compile(qa, trainset=trainset, num_trials=25)

# 5. Use the compiled program (portable artifact)
answer = compiled_qa(question="What is DSPy?").answer

核心原则

1. DSPy 是编译器，而不是链式框架。 你用 Python 控制流和类型签名定义程序结构，由编译器优化提示词。这与 LangChain 的显式提示词组合有本质区别。

2. 签名定义任务。 输入／输出字段对及其可选描述共同构成任务定义。语法为 input1, input2 -> output1, output2。

3. 模块是程序组件。 包括 dspy.Predict（直接预测）、dspy.ChainOfThought（推理）、dspy.ReAct（工具使用）和自定义的 dspy.Module 子类。通过 Python 控制流（if/for/while）组合这些模块。

4. 优化器调整提示词，而不是权重。 多种优化器（teleprompter）可调整指令、少样本示例，或两者兼顾。选择取决于瓶颈和预算。请参阅优化器速查表。

5. 编译一次，服务多次。 编译开销很大（$3-$300+）。通过 program.save(path) 可将输出保存为可移植的制品。推理开销很低。

6. 积极使用缓存。 DSPy 默认缓存所有 LM 调用。请为当前客户端设置 DSPY_CACHEDIR。使用 dspy.LM(..., cache=False) 可禁用缓存。

从哪里开始

你已有……	从这里开始
什么都没有——正在探索 DSPy	了解其范式（先阅读本页），然后构建一个简单的 Predict 程序
一个想要优化的可用提示词	将其迁移到 DSPy Signature，添加 ChainOfThought，然后使用 BootstrapFewShot 编译
一个多步骤流水线	使用 Python 控制流构建自定义 dspy.Module，然后使用 MIPROv2 编译
一个 Agent／工具使用任务	使用带工具的 dspy.ReAct，并通过 GEPA 或 AvatarOptimizer 编译
正在比较框架	请参阅框架选择指南

快速参考

任务	方法	参考
基本预测	dspy.Predict(signature)	references/core-modules.md
带推理	dspy.ChainOfThought(signature)	references/core-modules.md
使用工具	dspy.ReAct(tools=tools)	references/agent-patterns.md
自定义程序	class MyProgram(dspy.Module)	references/program-patterns.md
快速优化	dspy.BootstrapFewShot(metric)	references/optimizer-guide.md
完整优化	dspy.MIPROv2(metric, auto="medium")	references/optimizer-guide.md
评估	dspy.Evaluate(metric=fn, devset=examples)	references/evaluation.md
保存／加载	program.save(path) / program.load(path)	references/compilation-guide.md
检索	dspy.Retrieve(k=5)	references/program-patterns.md

框架选择指南

场景	选择	原因
提示词优化／编译程序	DSPy	唯一能针对某项指标自动优化提示词的框架
文档查询／RAG	LlamaIndex	数据摄取和检索是其一等功能
链／Agent 组合	LangChain	LCEL 是最简洁的管道式组合模型
状态机式多 Agent	LangGraph	图拓扑、子图和人在回路
搜索流水线	Haystack	对搜索工作负载而言，其流水线模型更成熟
基于角色的团队	CrewAI	更高层级的 Agent 抽象

参考文件

参考资料	加载时机	文件
核心模块	使用 Predict、ChainOfThought、ReAct 构建程序时	references/core-modules.md
优化器指南	选择和配置优化器时	references/optimizer-guide.md
程序模式	RAG、分类、多步骤任务、工具使用	references/program-patterns.md
评估	指标、评估循环、数据集创建	references/evaluation.md
编译指南	缓存、成本管理、保存/加载	references/compilation-guide.md
Agent 模式	ReAct Agent、工具使用、AvatarOptimizer	references/agent-patterns.md
常见问题与故障排除	常见错误及其修复方法	references/faq-and-troubleshooting.md
验证审计	对所有 API 声明进行研究验证	references/validation-audit.md
RAG 完整示例	完整的 RAG 编译及预期输出	references/example-rag-compilation.md

模板文件

模板	使用时机	文件
分类	使用 BootstrapFewShot 进行文本分类时	templates/classification.py
RAG 程序	使用 ColBERT 检索和 ChainOfThought 构建 RAG 时	templates/rag-program.py
多步骤推理	使用工具构建多步骤程序时	templates/multi-step.py

脚本

脚本	用途	文件
check-setup	验证 DSPy 的安装和配置	scripts/check-setup.py

故障排除

症状	可能原因	修复方法	参考资料
编译速度过慢	候选项/线程过多	减少 num_candidates 或使用 auto="light"	references/optimizer-guide.md
编译成本过高	未启用缓存	启用 DSPY_CACHEDIR	references/compilation-guide.md
上下文过长	示例过多	减少 max_bootstrapped_demos 和 max_labeled_demos	references/faq-and-troubleshooting.md
编译后质量下降	瓶颈对应的优化器选择错误	查看速查表：指令、示例还是权重	references/optimizer-guide.md
程序没有改进	指标缺乏区分度	使用返回 float 而不是 bool 的指标	references/evaluation.md
子模块未更新	已设置 _compiled 标记	重新编译前设置 module._compiled = False	references/compilation-guide.md

何时不应使用 DSPy

• 简单的单提示词应用——直接调用原始 API 更简单
• 需要预构建的应用模块（PDF 问答、文本转 SQL）——使用 LlamaIndex 或 LangChain
• 没有优化预算的一次性任务——DSPy 编译器的开销无法摊销
• 对延迟有实时严格要求——编译在开发时进行，但不会增加推理开销