dspy-fundamentals

DSPy 基础（3.2.x）

DSPy 是“提示词领域的 PyTorch”——你声明 Signature（带类型的输入/输出契约），将它们组合成 Module，再让优化器（而不是你）调整指令和少样本示例。永远不要手写原始提示词。

一段话了解模型

使用 dspy.configure(lm=...) 全局配置单个 LM。定义一个 dspy.Signature 子类，并使用 dspy.InputField() / dspy.OutputField()（文档字符串会成为指令）。将其封装在预测器中——dspy.Predict（直接预测）、dspy.ChainOfThought（添加推理）、dspy.ReAct（使用工具的 Agent）、dspy.ProgramOfThought（执行代码）或 dspy.RLM（长上下文）。继承 dspy.Module 来组合多步程序。对于内置提供商，使用 dspy.LM("provider/model")；对于真正自定义的后端，继承 dspy.BaseLM。之后可使用 GEPA 进行优化。

标准模板

import dspy

dspy.configure(lm=dspy.LM("openai/gpt-4o"), track_usage=True)

class QuestionAnswer(dspy.Signature):
    """Answer questions with rigorous step-by-step reasoning."""
    question: str = dspy.InputField()
    answer: str = dspy.OutputField(desc="concise final answer")

class QAProgram(dspy.Module):
    def __init__(self):
        super().__init__()
        self.solve = dspy.ChainOfThought(QuestionAnswer)

    def forward(self, question: str) -> dspy.Prediction:
        return self.solve(question=question)

program = QAProgram()
pred = program(question="What is 2 + 2?")
print(pred.reasoning, pred.answer)

预测器速查表（DSPy 3.2.x）

预测器	适用场景	增加内容
dspy.Predict(sig)	简单的结构化输入/输出	无——只有 Signature
dspy.ChainOfThought(sig)	推理任务	一个 reasoning 输出字段
dspy.ReAct(sig, tools=[...], max_iters=20)	使用工具的 Agent	Thought/Action/Observation 循环
dspy.ProgramOfThought(sig, max_iters=3)	数学/数据任务	生成并运行 Python（需要 Deno）
dspy.RLM(sig, ...)	长上下文 / 代码库	递归 REPL 探索（参见 dspy-rlm-module）

带类型的输出——在字段上使用 Pydantic，而不是 TypedPredictor

dspy.TypedPredictor 已被取代；现在 dspy.Predict 可通过字段注解原生处理 Pydantic 类型。

from pydantic import BaseModel
from typing import Literal

class Entity(BaseModel):
    name: str
    kind: Literal["person", "org", "place"]

class ExtractEntities(dspy.Signature):
    """Extract named entities from text."""
    text: str = dspy.InputField()
    entities: list[Entity] = dspy.OutputField()

extractor = dspy.Predict(ExtractEntities)

保存和加载

有两种模式——请了解它们的区别：

# State-only (portable JSON; you must rebuild the architecture to load)
program.save("program.json", save_program=False)
new = QAProgram(); new.load("program.json")

# Full program (cloudpickle into a directory; restores everything)
program.save("./program_dir/", save_program=True)
restored = dspy.load("./program_dir/")

版本控制优先使用仅状态模式；部署制品使用完整程序模式。

必须避免的十种反模式

1. 硬编码提示词字符串（"You are a helpful assistant..."）——改用 Signature。
2. 在新代码中使用 dspy.TypedPredictor(...)——改用带有 Pydantic 字段的 dspy.Predict。
3. 使用 dspy.OpenAI(...) / dspy.settings.configure(...)——改用 dspy.configure(lm=dspy.LM(...))。
4. 对内置提供商使用特定于提供商的 LM 类——改用 dspy.LM("provider/model")。如果 DSPy 未提供你的后端，请继承 dspy.BaseLM。
5. 用一个庞大的预测器完成五项任务——拆分成带有命名子预测器的 Module。
6. 手动修改 signature.instructions——交给优化器处理。
7. 在 Signature 文档字符串中内联少样本示例——对它们进行引导/优化。
8. 使用 pickle.dump(program)——改用 program.save(...)。
9. 没有理由却在构造模块时为其单独设置 LM——全局配置，只在需要混用模型时才覆盖。
10. 训练优化器时使用含糊的指标（是/否、仅精确匹配）——参见 dspy-evaluation-harness。

配置 LM

dspy.configure(
    lm=dspy.LM("openai/gpt-4o", temperature=0.0, max_tokens=2000),
    track_usage=True,        # accumulate token counts on predictions
    async_max_workers=4,     # for .acall / batch
)

DSPy 3.2.x 默认会在模块调用传入额外输入字段，或传入的值与 Signature 声明的类型不匹配时发出警告。首先应将这类警告视为调用位置的错误；如果你有意传入预先序列化的值，可通过 dspy.configure(warn_on_type_mismatch=False) 关闭警告。

常见的提供商前缀：openai/、anthropic/、azure/、vertex_ai/、bedrock/、ollama/。对于本地 Ollama：dspy.LM("ollama_chat/llama3.1:8b", api_base="http://localhost:11434")。

后续阅读

• 衡量质量 → dspy-evaluation-harness
• 自动优化 → dspy-gepa-optimizer
• 上下文超过 100k 个 token → dspy-rlm-module
• 完整工作流 → dspy-advanced-workflow
• 完整 API 参考 → reference.md
• 可运行示例 → example_qa.py