dspy-fundamentals

DSPy の基礎（3.2.x）

DSPy は「プロンプトのための PyTorch」です。シグネチャ（型付き I/O コントラクト）を宣言し、それらをモジュールに組み合わせて、オプティマイザーに（自分ではなく）指示と少数ショット例を調整させます。生のプロンプトは決して書かないでください。

1 段落でわかるモデル

dspy.configure(lm=...) で LM をグローバルに 1 つ設定します。dspy.InputField()／dspy.OutputField() を使って dspy.Signature のサブクラスを定義します（docstring が指示になります）。それを予測器でラップします。dspy.Predict（直接実行）、dspy.ChainOfThought（推論を追加）、dspy.ReAct（ツールを使用するエージェント）、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)	シンプルな構造化 I/O	なし — シグネチャのみ
dspy.ChainOfThought(sig)	推論タスク	reasoning 出力フィールド
dspy.ReAct(sig, tools=[...], max_iters=20)	ツールを使用するエージェント	思考／アクション／観察のループ
dspy.ProgramOfThought(sig, max_iters=3)	数学／データのタスク	Python を生成して実行（Deno が必要）
dspy.RLM(sig, ...)	長いコンテキスト／コードベース	再帰的な REPL 探索（dspy-rlm-module を参照）

型付き出力 — TypedPredictor ではなくフィールドに Pydantic を使う

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)

保存と読み込み

モードは 2 種類あります。違いを把握してください。

# 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/")

バージョン管理には状態のみの形式を、デプロイ用アーティファクトには完全なプログラム形式をおすすめします。

避けるべき 10 のアンチパターン

1. ハードコードしたプロンプト文字列（"You are a helpful assistant..."） — シグネチャを書きます。
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. 5 つの仕事をこなす巨大なモノリシック予測器 — 名前付きのサブ予測器を持つ Module に分解します。
6. signature.instructions を手作業で変更する — オプティマイザーに任せます。
7. 少数ショットのデモをシグネチャの docstring に直接埋め込む — ブートストラップ／最適化します。
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 は、モジュールの呼び出しで余分な入力フィールドが渡された場合や、シグネチャで宣言された型と一致しない値が渡された場合、デフォルトで警告します。まずはこれらの警告を呼び出し箇所のバグとして扱ってください。シリアライズ済みの値を意図的に渡している場合は、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 トークンを超えるコンテキスト → dspy-rlm-module
• パイプライン全体 → dspy-advanced-workflow
• API リファレンス全体 → reference.md
• 実行可能な例 → example_qa.py