Predict

v3.0.3

Predict是DSPy中最基础的模块，用于执行简单的预测任务。它直接将输入映射到输出，适合分类、回归等基础机器学习任务。

class Predict(dspy.Module)

初始化参数

signature

str

定义模块输入输出的签名字符串，如 "text -> sentiment: str"

lm

LM, optional

使用的语言模型，如果未指定则使用默认配置

temperature

float, optional

生成温度，控制输出的随机性，默认0.0

使用示例

示例代码
import dspy
# 创建文本分类器
classifier = dspy.Predict("text -> sentiment: str")
# 使用分类器
result = classifier(text="我喜欢这个产品！")
print(result.sentiment)  # 输出: positive

方法详解

call(self, **kwargs)

执行预测任务的主要方法。

参数:

**kwargs

dict

根据签名定义的输入参数

返回:

Prediction对象，包含签名定义的输出字段

使用示例
# 多输入示例
math_solver = dspy.Predict("a: float, b: float -> sum: float, product: float")
result = math_solver(a=5, b=3)
print(result.sum)      # 8.0
print(result.product)  # 15.0

适用场景

适合使用

• 简单的分类任务
• 文本生成任务
• 数据转换任务
• 快速原型开发

不适合使用

• 复杂推理任务
• 多步骤问题求解
• 需要外部工具的场景
• 高精度要求的任务

ChainOfThought

v3.0.3

ChainOfThought模块通过生成中间推理步骤来提高答案的准确性。它特别适合需要逻辑推理的复杂问题，能够显著提高模型的表现。

class ChainOfThought(dspy.Module)

核心优势

• 推理过程可见 - 可以查看模型的思考步骤
• 准确性更高 - 通过逐步推理减少错误
• 适合复杂问题 - 处理需要多步推理的任务
• 易于调试 - 可以分析推理过程中的问题

使用示例

基础示例
import dspy
# 创建推理模块
reasoner = dspy.ChainOfThought("question -> answer: str")
# 解决复杂问题
result = reasoner(question="如果所有的鸟都会飞，企鹅是鸟，那么企鹅会飞吗？")
print("答案:", result.answer)
print("推理过程:", result.reasoning)

数学问题解决示例

数学推理示例
# 数学问题求解器
math_solver = dspy.ChainOfThought("problem -> solution: float, steps: str")
# 解决数学问题
problem = "一个长方形的长是8米，宽是5米，求它的面积和周长。"
result = math_solver(problem=problem)
print(f"面积: {result.solution['area']}")
print(f"周长: {result.solution['perimeter']}")
print(f"解题步骤: {result.steps}")

最佳实践

• 为复杂问题设计清晰的输入输出签名
• 使用多个输出字段来分离答案和推理过程
• 在调试时检查reasoning字段来理解模型思维
• 结合优化器来进一步提升性能

ReAct

v3.0.3

ReAct模块结合了推理和行动，可以与外部工具和环境交互，是构建AI Agent的理想选择。它能够让AI系统在思考的同时采取行动，实现更复杂的任务处理。

class ReAct(dspy.Module)

初始化参数

signature

str

定义Agent输入输出的签名字符串

tools

list, optional

可用的工具函数列表

max_iters

int, optional

最大迭代次数，默认5

使用示例

基础示例
import dspy
# 定义工具函数
def search(query: str) -> str:
    # 模拟搜索功能
    return f"搜索结果: {query} 的相关信息"
def calculate(expression: str) -> str:
    # 模拟计算功能
    try:
        result = eval(expression)
        return f"计算结果: {result}"
    except:
        return "计算错误"
# 创建ReAct Agent
agent = dspy.ReAct(
    "question -> answer: str",
    tools=[search, calculate],
    max_iters=3
)
# 使用Agent
result = agent(question="搜索机器学习的定义，然后计算2+2*2")
print(result.answer)

复杂Agent示例

复杂Agent系统
import dspy
from datetime import datetime
# 定义多个工具
def get_current_time():
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
def weather_api(location: str):
    # 模拟天气API
    weather_data = {
        "北京": "晴天，25°C",
        "上海": "多云，22°C",
        "广州": "小雨，28°C"
    }
    return weather_data.get(location, "未知地区")
def news_search(keyword: str):
    # 模拟新闻搜索
    return f"关于'{keyword}'的最新新闻：..."
# 创建智能助手Agent
assistant = dspy.ReAct(
    "request -> response: str, actions_taken: list[str]",
    tools=[get_current_time, weather_api, news_search],
    max_iters=5
)
# 测试不同的请求
requests = [
    "现在几点了？北京天气怎么样？",
    "搜索最近关于人工智能的新闻",
    "告诉我现在时间和上海天气"
]
for request in requests:
    print(f"\n请求: {request}")
    result = assistant(request=request)
    print(f"回答: {result.response}")
    print(f"执行的操作: {result.actions_taken}")
    print("-" * 50)

ReAct最佳实践

• 工具设计 - 工具函数应该有清晰的输入输出和错误处理
• 迭代控制 - 设置合理的max_iters避免无限循环
• 状态管理 - 考虑Agent的状态持久化和恢复
• 性能监控 - 跟踪Agent的决策过程和工具使用情况
• 安全性 - 验证工具输入，防止恶意操作

BootstrapRS

v3.0.3

BootstrapRS优化器通过自举样例来优化模块的提示和权重。它从少量示例开始，自动生成更多高质量的示例，然后使用这些示例来优化整个系统。

class BootstrapRS(dspy.Optimizer)

初始化参数

metric

function

评估函数，用于衡量模块性能

max_bootstrapped_demos

int, optional

最大自举示例数，默认4

max_labeled_demos

int, optional

最大标注示例数，默认16

使用示例

基础示例
import dspy
# 1. 准备训练数据
trainset = [
    dspy.Example(
        question="中国的首都是哪里？",
        answer="北京"
    ).with_inputs("question"),
    dspy.Example(
        question="2+2等于多少？",
        answer="4"
    ).with_inputs("question"),
]
# 2. 定义评估函数
def exact_match_metric(example, pred, trace=None):
    return example.answer.lower() == pred.answer.lower()
# 3. 创建基础模块
qa_module = dspy.ChainOfThought("question -> answer: str")
# 4. 创建优化器
optimizer = dspy.BootstrapRS(
    metric=exact_match_metric,
    max_bootstrapped_demos=4,
    max_labeled_demos=16
)
# 5. 优化模块
optimized_module = optimizer.compile(qa_module, trainset=trainset)
# 6. 使用优化后的模块
result = optimized_module(question="太阳从哪个方向升起？")
print(f"答案: {result.answer}")

高级配置示例

高级配置
import dspy
# 复杂的评估函数
def complex_metric(example, pred, trace=None):
    # 准确性评分
    accuracy = 1.0 if example.answer.lower() == pred.answer.lower() else 0.0
    
    # 格式检查
    format_score = 1.0 if len(pred.answer) > 0 else 0.0
    
    # 综合评分
    return accuracy * 0.8 + format_score * 0.2
# 创建优化器并进行优化
optimizer = dspy.BootstrapRS(
    metric=complex_metric,
    max_bootstrapped_demos=8,
    max_labeled_demos=32
)
# 准备更多训练数据
extended_trainset = [
    # 基础问答
    dspy.Example(question="水的沸点是多少？", answer="100°C").with_inputs("question"),
    dspy.Example(question="地球有几个大洲？", answer="7个").with_inputs("question"),
    # 推理问题
    dspy.Example(question="如果所有鸟都会飞，企鹅是鸟，那么企鹅会飞吗？", answer="不会，企鹅是例外").with_inputs("question"),
    # 数学问题
    dspy.Example(question="一个三角形的内角和是多少度？", answer="180度").with_inputs("question"),
]
# 优化模块
qa_module = dspy.ChainOfThought("question -> answer: str")
optimized_qa = optimizer.compile(qa_module, trainset=extended_trainset)
# 评估优化效果
test_questions = [
    "一年有多少天？",
    "如果A>B且B>C，那么A>C吗？",
    "圆的周长公式是什么？"
]
print("=== 优化效果测试 ===")
for question in test_questions:
    result = optimized_qa(question=question)
    print(f"Q: {question}")
    print(f"A: {result.answer}")
    print("-" * 40)

优化器选择指南

BootstrapRS - 适合：

• 有少量标注数据的任务
• 需要快速原型验证的场景
• 成本敏感的优化需求

GEPA - 适合：

• 需要优化指令措辞的任务
• 复杂的推理和决策任务
• 对提示质量要求高的场景

MIPROv2 - 适合：

• 多步骤的复杂任务
• 需要多种提示策略的场景
• 高级AI应用开发

ProgramOfThought

ProgramOfThought模块通过生成和执行程序代码来解决复杂问题，特别适合需要精确计算和逻辑推理的任务。

核心特性

• 代码生成 - 自动生成解决任务的程序代码
• 执行验证 - 执行生成的代码并验证结果
• 错误处理 - 自动修复代码中的错误
• 多步推理 - 适合需要多步计算的问题

使用示例

数学问题求解
import dspy
# 创建ProgramOfThought模块
math_solver = dspy.ProgramOfThought("problem -> solution: float, code: str, explanation: str")
# 解决复杂数学问题
problem = "计算一个半径为5的圆的面积，然后减去一个边长为3的正方形的面积"
result = math_solver(problem=problem)
print(f"问题: {problem}")
print(f"解决方案: {result.solution}")
print(f"生成的代码:\n{result.code}")
print(f"解释: {result.explanation}")

GEPA

GEPA (Gradient-based Evolution of Prompts and Architectures) 优化器通过梯度指导来优化提示和架构，能够发现更好的指令和模块配置。

class GEPA(dspy.Optimizer)

初始化参数

metric

function

评估函数，用于衡量性能

num_trials

int, optional

试验次数，默认10

max_paraphrases

int, optional

最大释义数，默认5

使用示例

GEPA优化示例
import dspy
# 定义评估函数
def sentiment_accuracy(example, pred, trace=None):
    return example.sentiment == pred.sentiment
# 创建GEPA优化器
optimizer = dspy.GEPA(
    metric=sentiment_accuracy,
    num_trials=15,
    max_paraphrases=8
)
# 准备训练数据
trainset = [
    dspy.Example(text="我喜欢这个产品！", sentiment="positive").with_inputs("text"),
    dspy.Example(text="质量太差了", sentiment="negative").with_inputs("text"),
]
# 优化模块
classifier = dspy.Predict("text -> sentiment: str")
optimized_classifier = optimizer.compile(classifier, trainset=trainset)

MIPROv2

MIPROv2 (Multi-prompt Instruction PRopOsal) 优化器通过生成和评估多个提示指令来找到最优配置，特别适合复杂的多步骤任务。

class MIPROv2(dspy.Optimizer)

初始化参数

metric

function

评估函数

num_candidates

int, optional

候选提示数，默认10

num_threads

int, optional

并行线程数，默认6

使用示例

MIPROv2优化示例
import dspy
# 创建MIPROv2优化器
optimizer = dspy.MIPROv2(
    metric=custom_metric,
    num_candidates=15,
    num_threads=8
)
# 优化复杂的多步骤模块
complex_module = dspy.ChainOfThought("problem -> analysis: str, solution: str, recommendations: list[str]")
optimized_module = optimizer.compile(complex_module, trainset=trainset)

Example

Example类用于创建和管理训练示例，是DSPy优化器的重要输入。它提供了便捷的方式来组织和标注训练数据。

class Example(dict)

使用示例

创建和使用示例
import dspy
# 创建示例
example = dspy.Example(
    question="什么是机器学习？",
    answer="机器学习是人工智能的一个分支...",
    category="AI"
)
# 指定输入字段
example_with_inputs = example.with_inputs("question")
# 创建训练集
trainset = [
    dspy.Example(question="2+2=?", answer="4").with_inputs("question"),
    dspy.Example(question="3*4=?", answer="12").with_inputs("question"),
]

Predict

初始化参数

使用示例

方法详解

__call__(self, **kwargs)

适用场景

适合使用

不适合使用

相关模块

ChainOfThought

核心优势

使用示例

数学问题解决示例

最佳实践

ReAct

初始化参数

使用示例

复杂Agent示例

ReAct最佳实践

BootstrapRS

初始化参数

使用示例

高级配置示例

优化器选择指南

ProgramOfThought

核心特性

使用示例

GEPA

初始化参数

使用示例

MIPROv2

初始化参数

使用示例

Example

使用示例

call(self, **kwargs)