DSPy.rb专家技能Skill dspy-ruby

---

名称: dspy-ruby 描述: 此技能应在使用DSPy.rb时使用，DSPy.rb是一个用于构建类型安全、可组合的LLM应用程序的Ruby框架。在实现可预测的AI功能、创建LLM签名和模块、配置语言模型提供者（OpenAI、Anthropic、Gemini、Ollama）、构建带有工具的代理系统、优化提示或测试Ruby应用程序中的LLM驱动功能时使用此技能。

DSPy.rb 专家

概述

DSPy.rb 是一个 Ruby 框架，使开发者能够编程 LLMs，而不是提示它们。通过类型安全、可组合的模块定义应用需求，这些模块可以像常规代码一样进行测试、优化和版本控制，而不是手动制作提示。

此技能提供全面指导，包括：

• 为LLM操作创建类型安全的签名
• 构建可组合的模块和工作流
• 配置多个LLM提供者
• 使用工具实现代理
• 测试和优化LLM应用程序
• 生产部署模式

核心能力

1. 类型安全签名

为LLM操作创建输入/输出合同，具有运行时类型检查。

何时使用：定义任何LLM任务，从简单分类到复杂分析。

快速参考：

class EmailClassificationSignature < DSPy::Signature
  description "分类客户支持邮件"

  input do
    const :email_subject, String
    const :email_body, String
  end

  output do
    const :category, T.enum(["技术", "账单", "一般"])
    const :priority, T.enum(["低", "中", "高"])
  end
end

模板：参见assets/signature-template.rb获取综合示例，包括：

• 带多字段类型的基本签名
• 用于多模态任务的视觉签名
• 情感分析签名
• 代码生成签名

最佳实践：

• 始终提供清晰、具体的描述
• 为约束输出使用枚举
• 使用desc:参数包含字段描述
• 尽可能使用特定类型而非通用String

完整文档：参见references/core-concepts.md中关于签名和类型安全的部分。

2. 可组合模块

构建可重用、可链接的模块，封装LLM操作。

何时使用：实现任何LLM驱动的功能，特别是复杂多步骤工作流。

快速参考：

class EmailProcessor < DSPy::Module
  def initialize
    super
    @classifier = DSPy::Predict.new(EmailClassificationSignature)
  end

  def forward(email_subject:, email_body:)
    @classifier.forward(
      email_subject: email_subject,
      email_body: email_body
    )
  end
end

模板：参见assets/module-template.rb获取综合示例，包括：

• 带单个预测器的基本模块
• 链接模块的多步骤管道
• 带条件逻辑的模块
• 错误处理和重试模式
• 带历史的状态模块
• 缓存实现

模块组合：链接模块以创建复杂工作流：

class Pipeline < DSPy::Module
  def initialize
    super
    @step1 = Classifier.new
    @step2 = Analyzer.new
    @step3 = Responder.new
  end

  def forward(input)
    result1 = @step1.forward(input)
    result2 = @step2.forward(result1)
    @step3.forward(result2)
  end
end

完整文档：参见references/core-concepts.md中关于模块和模块组合的部分。

3. 多种预测器类型

为任务选择合适的预测器：

Predict：基本的LLM推理，带类型安全输入/输出

predictor = DSPy::Predict.new(TaskSignature)
result = predictor.forward(input: "data")

ChainOfThought：添加自动推理以提高准确性

predictor = DSPy::ChainOfThought.new(TaskSignature)
result = predictor.forward(input: "data")
# 返回：{ reasoning: "...", output: "..." }

ReAct：使用工具的代理，带迭代推理

predictor = DSPy::ReAct.new(
  TaskSignature,
  tools: [SearchTool.new, CalculatorTool.new],
  max_iterations: 5
)

CodeAct：动态代码生成（需要dspy-code_act gem）

predictor = DSPy::CodeAct.new(TaskSignature)
result = predictor.forward(task: "计算5的阶乘")

何时使用每种：

• Predict：简单任务、分类、提取
• ChainOfThought：复杂推理、分析、多步骤思考
• ReAct：需要外部工具的任务（搜索、计算、API调用）
• CodeAct：最好通过生成代码解决的任务

完整文档：参见references/core-concepts.md中关于预测器的部分。

4. LLM提供者配置

支持OpenAI、Anthropic Claude、Google Gemini、Ollama和OpenRouter。

快速配置示例：

# OpenAI
DSPy.configure do |c|
  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
    api_key: ENV['OPENAI_API_KEY'])
end

# Anthropic Claude
DSPy.configure do |c|
  c.lm = DSPy::LM.new('anthropic/claude-3-5-sonnet-20241022',
    api_key: ENV['ANTHROPIC_API_KEY'])
end

# Google Gemini
DSPy.configure do |c|
  c.lm = DSPy::LM.new('gemini/gemini-1.5-pro',
    api_key: ENV['GOOGLE_API_KEY'])
end

# Local Ollama（免费、私有）
DSPy.configure do |c|
  c.lm = DSPy::LM.new('ollama/llama3.1')
end

模板：参见assets/config-template.rb获取综合示例，包括：

• 基于环境的配置
• 不同任务的多模型设置
• 带可观察性的配置（OpenTelemetry、Langfuse）
• 重试逻辑和回退策略
• 预算跟踪
• Rails初始化模式

提供者兼容性矩阵：

特性	OpenAI	Anthropic	Gemini	Ollama
结构化输出	✅	✅	✅	✅
视觉（图像）	✅	✅	✅	⚠️ 有限
图像URL	✅	❌	❌	❌
工具调用	✅	✅	✅	变量

成本优化策略：

• 开发：Ollama（免费）或gpt-4o-mini（廉价）
• 测试：gpt-4o-mini，温度=0.0
• 生产简单任务：gpt-4o-mini、claude-3-haiku、gemini-1.5-flash
• 生产复杂任务：gpt-4o、claude-3-5-sonnet、gemini-1.5-pro

完整文档：参见references/providers.md获取所有配置选项、提供者特定功能和故障排除。

5. 多模态和视觉支持

使用统一的DSPy::Image接口处理图像和文本。

快速参考：

class VisionSignature < DSPy::Signature
  description "分析图像并回答问题"

  input do
    const :image, DSPy::Image
    const :question, String
  end

  output do
    const :answer, String
  end
end

predictor = DSPy::Predict.new(VisionSignature)
result = predictor.forward(
  image: DSPy::Image.from_file("路径/到/图像.jpg"),
  question: "可见什么物体？"
)

图像加载方法：

# 从文件
DSPy::Image.from_file("路径/到/图像.jpg")

# 从URL（仅OpenAI）
DSPy::Image.from_url("https://example.com/image.jpg")

# 从base64
DSPy::Image.from_base64(base64_data, mime_type: "image/jpeg")

提供者支持：

• OpenAI：完全支持，包括URL
• Anthropic、Gemini：仅base64或文件加载
• Ollama：有限多模态，取决于模型

完整文档：参见references/core-concepts.md中关于多模态支持的部分。

6. 测试LLM应用程序

为LLM逻辑编写标准RSpec测试。

快速参考：

RSpec.describe EmailClassifier do
  before do
    DSPy.configure do |c|
      c.lm = DSPy::LM.new('openai/gpt-4o-mini',
        api_key: ENV['OPENAI_API_KEY'])
    end
  end

  it '正确分类技术邮件' do
    classifier = EmailClassifier.new
    result = classifier.forward(
      email_subject: "无法登录",
      email_body: "无法访问账户"
    )

    expect(result[:category]).to eq('技术')
    expect(result[:priority]).to be_in(['高', '中', '低'])
  end
end

测试模式：

• 为单元测试模拟LLM响应
• 使用VCR进行确定性API测试
• 测试类型安全和验证
• 测试边缘情况（空输入、特殊字符、长文本）
• 集成测试完整工作流

完整文档：参见references/optimization.md中关于测试的部分。

7. 优化和改进

使用优化技术自动改进提示和模块。

MIPROv2优化：

require 'dspy/mipro'

# 定义评估指标
def accuracy_metric(example, prediction)
  example[:expected_output][:category] == prediction[:category] ? 1.0 : 0.0
end

# 准备训练数据
training_examples = [
  {
    input: { email_subject: "...", email_body: "..." },
    expected_output: { category: '技术' }
  },
  # 更多示例...
]

# 运行优化
optimizer = DSPy::MIPROv2.new(
  metric: method(:accuracy_metric),
  num_candidates: 10
)

optimized_module = optimizer.compile(
  EmailClassifier.new,
  trainset: training_examples
)

A/B测试不同方法：

# 测试ChainOfThought vs ReAct
approach_a_score = evaluate_approach(ChainOfThoughtModule, test_set)
approach_b_score = evaluate_approach(ReActModule, test_set)

完整文档：参见references/optimization.md中关于优化的部分。

8. 可观察性和监控

跟踪生产中的性能、令牌使用和行为。

OpenTelemetry集成：

require 'opentelemetry/sdk'

OpenTelemetry::SDK.configure do |c|
  c.service_name = '我的dspy应用'
  c.use_all
end

# DSPy自动创建跟踪

Langfuse跟踪：

DSPy.configure do |c|
  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
    api_key: ENV['OPENAI_API_KEY'])

  c.langfuse = {
    public_key: ENV['LANGFUSE_PUBLIC_KEY'],
    secret_key: ENV['LANGFUSE_SECRET_KEY']
  }
end

自定义监控：

• 令牌跟踪
• 性能监控
• 错误率跟踪
• 自定义日志

完整文档：参见references/optimization.md中关于可观察性的部分。

快速入门工作流

对于新项目

1. 安装DSPy.rb和提供者gem：

gem install dspy dspy-openai  # 或dspy-anthropic、dspy-gemini

2. 配置LLM提供者（参见assets/config-template.rb）：

require 'dspy'

DSPy.configure do |c|
  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
    api_key: ENV['OPENAI_API_KEY'])
end

3. 创建签名（参见assets/signature-template.rb）：

class MySignature < DSPy::Signature
  description "任务的清晰描述"

  input do
    const :input_field, String, desc: "描述"
  end

  output do
    const :output_field, String, desc: "描述"
  end
end

4. 创建模块（参见assets/module-template.rb）：

class MyModule < DSPy::Module
  def initialize
    super
    @predictor = DSPy::Predict.new(MySignature)
  end

  def forward(input_field:)
    @predictor.forward(input_field: input_field)
  end
end

5. 使用模块：

module_instance = MyModule.new
result = module_instance.forward(input_field: "测试")
puts result[:output_field]

6. 添加测试（参见references/optimization.md）：

RSpec.describe MyModule do
  it '产生预期输出' do
    result = MyModule.new.forward(input_field: "测试")
    expect(result[:output_field]).to be_a(String)
  end
end

对于Rails应用

1. 添加到Gemfile：

gem 'dspy'
gem 'dspy-openai'  # 或其他提供者

2. 在config/initializers/dspy.rb创建初始化器（参见assets/config-template.rb获取完整示例）：

require 'dspy'

DSPy.configure do |c|
  c.lm = DSPy::LM.new('openai/gpt-4o-mini',
    api_key: ENV['OPENAI_API_KEY'])
end

3. 在app/llm/目录创建模块：

# app/llm/email_classifier.rb
class EmailClassifier < DSPy::Module
  # 实现这里
end

4. 在控制器/服务中使用：

class EmailsController < ApplicationController
  def classify
    classifier = EmailClassifier.new
    result = classifier.forward(
      email_subject: params[:subject],
      email_body: params[:body]
    )
    render json: result
  end
end

常见模式

模式：多步骤分析管道

class AnalysisPipeline < DSPy::Module
  def initialize
    super
    @extract = DSPy::Predict.new(ExtractSignature)
    @analyze = DSPy::ChainOfThought.new(AnalyzeSignature)
    @summarize = DSPy::Predict.new(SummarizeSignature)
  end

  def forward(text:)
    extracted = @extract.forward(text: text)
    analyzed = @analyze.forward(data: extracted[:data])
    @summarize.forward(analysis: analyzed[:result])
  end
end

模式：带工具的代理

class ResearchAgent < DSPy::Module
  def initialize
    super
    @agent = DSPy::ReAct.new(
      ResearchSignature,
      tools: [
        WebSearchTool.new,
        DatabaseQueryTool.new,
        SummarizerTool.new
      ],
      max_iterations: 10
    )
  end

  def forward(question:)
    @agent.forward(question: question)
  end
end

class WebSearchTool < DSPy::Tool
  def call(query:)
    results = perform_search(query)
    { results: results }
  end
end

模式：条件路由

class SmartRouter < DSPy::Module
  def initialize
    super
    @classifier = DSPy::Predict.new(ClassifySignature)
    @simple_handler = SimpleModule.new
    @complex_handler = ComplexModule.new
  end

  def forward(input:)
    classification = @classifier.forward(text: input)

    if classification[:complexity] == '简单'
      @simple_handler.forward(input: input)
    else
      @complex_handler.forward(input: input)
    end
  end
end

模式：带回退的重试

class RobustModule < DSPy::Module
  MAX_RETRIES = 3

  def forward(input, retry_count: 0)
    begin
      @predictor.forward(input)
    rescue DSPy::ValidationError => e
      if retry_count < MAX_RETRIES
        sleep(2 ** retry_count)
        forward(input, retry_count: retry_count + 1)
      else
        # 回退到默认或引发
        raise
      end
    end
  end
end

资源

此技能包含综合参考材料和模板：

参考（按需加载以获取详细信息）

• core-concepts.md：关于签名、模块、预测器、多模态支持和最佳实践的完整指南
• providers.md：所有LLM提供者配置、兼容性矩阵、成本优化和故障排除
• optimization.md：测试模式、优化技术、可观察性设置和监控

资产（快速入门的模板）

• signature-template.rb：签名示例，包括基本、视觉、情感分析和代码生成
• module-template.rb：模块模式，包括管道、代理、错误处理、缓存和状态管理
• config-template.rb：所有提供者、环境、可观察性和生产模式的配置示例

何时使用此技能

触发此技能当：

• 在Ruby应用程序中实现LLM驱动的功能
• 为AI操作创建类型安全的接口
• 构建使用工具的代理系统
• 设置或故障排除LLM提供者
• 优化提示并提高准确性
• 测试LLM功能
• 为AI应用添加可观察性
• 从手动提示工程转换为编程方法
• 调试DSPy.rb代码或配置问题