DSPy 3.5へ上げる前に直す6か所|OpenAI互換サーバーへの送り先、XMLになったプロンプト、ReActの結果を3.4.1と比べて検証

DSPy 3.5.0は、プロンプトと既定値とAPIを変えた

PythonのLLMライブラリDSPyの開発チームが、2026年11月10日(日本時間11日)に3.5.0を公開しました(DSPy 3.5.0のリリースノート)。DSPyは、LLMへのプロンプトを手で書く代わりに、入力と出力の欄(Signature)を宣言してプログラムとして組み立て、例や指示を自動で最適化できるライブラリです。

リリースノートは冒頭で、この版はプロンプト、既定値、APIを変えると書き、3.5への移行ガイドを読むよう求めています。既定のアダプター(Signatureをプロンプトに組み立て、LLMの答えを欄ごとに取り出す部品)がXML形式になり、モデル名をopenai/やazure/で指定したときは送り先のAPIが自動で選ばれるようになりました。LiteLLMとOpenAIのPythonライブラリは、追加で入れるものに変わっています。

この記事では、3.4.1と3.5.0を別々の仮想環境に入れ、手元で動かした疑似サーバー(届いた要求を記録するOpenAI互換のサーバー)へ同じコードで要求を送りました。上げると止まる書き方、止まらずに結果だけ変わる書き方、それぞれの直し方を順に説明します。

要点

3.5.0へ上げる前に、送り先・プロンプト・結果の読み方・インストールを確かめる

3.4.1と3.5.0に同じコードを実行させ、疑似サーバーに届いた要求と結果を比べました。

送り先

openai/とapi_baseの指定は/v1/responsesへ

3.4.1は/v1/chat/completionsでした。Responses APIのない接続先ではエラーになり、model_type="chat"で元の送り先に戻ります。

プロンプト

既定の形式がXMLのタグになる

3.4.1で保存した最適化済みのプログラムも、例がXMLで送られます。ChatAdapterとmodel_type="chat"を指定すると、Predictの要求は3.4.1と一致しました。

結果の読み方

ReActはhistory、ChainOfThoughtはReasoning型

r.trajectoryはAttributeErrorになり、reasoningをjson.dumpsに渡すとTypeErrorになります。

インストール

入るパッケージは68から26に減った

LiteLLMとOpenAIのライブラリは入りません。lm_studio/の指定や、api_version・extra_headers・extra_bodyなどを付けたdspy.LMは、dspy[litellm]を入れると送れます。

openai/とazure/の要求はResponses APIに送られる

OpenAIのAPIには、会話の形で答えを返すChat Completions API(/v1/chat/completions)と、新しいResponses API(/v1/responses)があります。vLLMやLM Studioのように手元でLLMを動かすサーバーにも、OpenAIと同じ形の要求を受け付けるもの(OpenAI互換サーバー)が多く、DSPyではopenai/で始まるモデル名にapi_baseで接続先を渡してつなぐ書き方がよく使われます。

import dspy

lm = dspy.LM("openai/my-model", api_base="http://localhost:8000/v1", api_key="dummy")
dspy.configure(lm=lm)
dspy.Predict("question -> answer")(question="日本の首都はどこですか")

移行ガイドによると、3.5.0ではdspy.LMのmodel_typeの既定が"auto"になり、OpenAIとAzureの指定ではResponses APIが選ばれます。疑似サーバーで要求のパスを記録すると、上のコードは3.4.1では/v1/chat/completions、3.5.0では/v1/responsesに届きました。

移行ガイドでは、Responses APIが選ばれるのはOpenAIとAzureの指定です。手元のサーバー向けに試した指定では、openai/とapi_baseの組み合わせが/v1/responsesに変わり、hosted_vllm/とollama_chat/はどちらの版でもChat Completionsの形式で送られました。

openai/…とapi_base

3.4.1 /v1/chat/completions

3.5.0 /v1/responses

上と同じでmodel_type="chat"を付ける

3.4.1 /v1/chat/completions

3.5.0 /v1/chat/completions

hosted_vllm/…、ollama_chat/…

3.4.1 Chat Completionsの形式

3.5.0 Chat Completionsの形式(変わらない)

lm_studio/…

3.4.1 /v1/chat/completions

3.5.0 ImportError(dspy[litellm]を入れると/v1/chat/completions)

azure/…(api_version付き)

3.4.1 /openai/deployments/(デプロイ名)/chat/completions

3.5.0 ImportError(dspy[litellm]を入れると/openai/responses)

2026年11月16日、macOS 27.0.1・Python 3.13.14で、要求を記録する疑似サーバーにdspy.Predictを1回ずつ実行した結果。openai/はdspy[litellm]を入れた3.5.0でも/v1/responsesでした。

疑似サーバーを/v1/responsesに404を返す設定にして、Chat Completionsだけに答える接続先を再現しました。3.5.0は/v1/responsesへ1回だけ要求を送り、次のエラーで止まりました。Chat Completionsへ送り直すことはありませんでした。

dspy.utils.exceptions.LMInvalidRequestError: [openai/mock-model] Not Found

角かっこの中のモデル名と末尾の文言(ここではNot Found)は、指定したモデル名と接続先が返す内容によって変わります。このエラーが出たら、dspy.LMにmodel_type="chat"を足します。疑似サーバーの同じ設定で、3.5.0の要求は/v1/chat/completionsに届き、答えが返りました。

lm = dspy.LM(
    "openai/my-model",
    api_base="http://localhost:8000/v1",
    api_key="dummy",
    model_type="chat",  # 3.5.0でChat Completions APIに固定する
)

接続先がResponses APIに対応していれば、既定のままでも動きます。ただし既定の送り先では、ReActの道具の呼び出しと結果が、Responses APIのfunction_callとfunction_call_outputという項目で送られました。この項目を読まない疑似サーバーでは、ReActが最後まで進まずに止まりました。道具を使うプログラムは、その接続先で一度動かして確かめます。

lm_studio/で始まる指定は、3.5.0ではLiteLLMを通して送られます。LiteLLMが入っていないと、要求を送る前にImportError: litellm is required to use LiteLLM engine.で止まりました。pip install "dspy[litellm]"で入れ直すと、3.4.1と同じく/v1/chat/completionsに届きました。

azure/は、api_versionを付けるかどうかで送り方が変わりました。api_versionを付けるとLiteLLMを通り、dspy[litellm]を入れた環境では/openai/responsesに届きました。model_type="chat"を付けると、3.4.1と同じ/openai/deployments/(デプロイ名)/chat/completionsに戻りました。api_versionを付けないと、LiteLLMなしで/openai/v1/responsesに送られ、model_type="chat"を付けると/openai/v1/chat/completionsに送られました。

既定のプロンプトはXMLのタグ形式になる

3.5.0の既定のアダプターはXMLAdapterです。dspy.Predict("question -> answer")で送られた最後のユーザーのメッセージを並べると、欄の区切りが[[ ## 欄の名前 ## ]]から<欄の名前>のタグに変わっていました。LLMへの指示の文面も変わるので、同じSignatureでも答えの形や精度が変わることがあります。

3.4.1(ChatAdapter)

欄を[[ ## ]]で区切り、completedで終える

[[ ## question ## ]]
日本の首都はどこですか

Respond with the corresponding output fields, starting with the field `[[ ## answer ## ]]`, and then ending with the marker for `[[ ## completed ## ]]`.

3.5.0(既定のXMLAdapter)

欄をタグで囲み、答えの形をタグで示す

<question>
日本の首都はどこですか
</question>

Output format (replace placeholders):
<answer>
{answer}
</answer>

Use this format for text outputs. Put field tags on separate lines. Write string values literally, without XML or JSON escaping.

疑似サーバーに届いた要求の最後のユーザーのメッセージ。2026年11月16日、macOS 27.0.1・Python 3.13.14で確認。システムのメッセージも同じ形式で変わります。

最適化して保存したプログラムにも影響します。3.4.1で例(質問と答えの組)を1つ入れてsave()したJSONを3.5.0でload()すると、版が違うという警告(There is a mismatch of dspy version between saved model and current environment.)が出たうえで読み込めました。ただし送られた要求では、保存した例もXMLのタグで書き直されていました。3.4.1で最適化した例と指示が、3.4.1とは違う形でLLMに届きます。

3.4.1と同じ要求を保ったまま上げたい場合は、ChatAdapterを明示します。上のmodel_type="chat"と合わせて指定すると、例を入れたPredictで送られたメッセージは3.4.1と1文字も違わず一致しました。

dspy.configure(lm=lm, adapter=dspy.ChatAdapter())

移行ガイドは、ChatAdapterで戻るのは欄の区切りだけで、この記事で後に説明するChainOfThoughtやReActの変更は戻らないと書いています。最適化済みのプログラムは、3.5.0の上で評価し直すよう求めています。まずChatAdapterとmodel_type="chat"で3.4.1と同じ要求を送れることを確かめ、XMLの形式へ移すかどうかは評価の点数を比べて決める、という順に分けると、上げたことによる差と形式の差を別々に測れます。

ChainOfThoughtのreasoningはdspy.Reasoning型になる

dspy.ChainOfThoughtは、答えの前にLLMに考えた過程を書かせ、pred.reasoningで読めるようにするモジュールです。3.4.1ではreasoningは文字列でした。3.5.0ではdspy.Reasoningという型になり、移行ガイドによるとNoneのこともあります。文字列として扱う操作を試すと、ほとんどは同じように動き、json.dumpsだけが止まりました。

pred.reasoningへの操作 3.4.1 3.5.0
isinstance(x, str) True False
len(x)、x + "!"、"答える" in x、str(x) 動く 動く(結果も同じ)
json.dumps({"r": x}) 動く TypeError
pred.toDict()["reasoning"] str str

dspy.ChainOfThought("question -> answer")の結果。2026年11月16日、macOS 27.0.1・Python 3.13.14で、model_type="chat"を指定して確認。3.5.0のjson.dumpsのエラーはTypeError: Object of type Reasoning is not JSON serializableでした。

評価のログをjson.dumpsで書き出している場合や、isinstance(..., str)で値を確かめている場合は、str(pred.reasoning)に直すか、pred.toDict()を使います。Noneのときに"None"という文字列にしないよう、先にNoneを確かめます。

プロンプトも変わります。移行ガイドによると、3.5.0はLLMが持つ推論の機能(答える前に考える機能)を優先して使い、使えない場合は短い計画を書かせます。今回の疑似サーバーへの要求では、3.4.1の出力欄reasoningの代わりに、plan(A short plan for solving the task.)という欄をLLMに書かせ、その内容がpred.reasoningに入りました。文字列のまま受け取りたい場合は、移行ガイドにあるrationale_field_type=strを付けます。

cot = dspy.ChainOfThought(
    "question -> answer",
    rationale_field_type=str,
)

これでpred.reasoningは文字列になり、出力欄もreasoningに戻りました。ChatAdapterとmodel_type="chat"も合わせて指定すると、今回の疑似サーバーへの要求では、ChainOfThought("question -> answer")で送られたメッセージが3.4.1と一致しました。rationale_field_typeを付けないと、planの欄があるぶん一致しません。

ReActの結果はtrajectoryからhistoryへ移る

3.5.0では、道具(関数)を呼びながら答えを探すdspy.ReActが、これまでReActV2と呼ばれていた新しい実装に置き換わりました。道具を1つ(都市の天気を返すget_weather)渡して同じ質問をすると、どちらの版も同じ答えを返し、結果の中身の形が変わりました。

3.4.1

r.trajectoryの辞書に、各回の考えと道具の結果が並ぶ

r = agent(question="東京の天気は?")
for k, v in r.trajectory.items():
    print(k, v)
# thought_0 天気を調べる。
# tool_name_0 get_weather
# tool_args_0 {'city': '東京'}
# observation_0 東京は晴れ …

結果のキーはtrajectory、reasoning、answer。疑似サーバーへの要求は3回(2回の手番と、答えをまとめる1回)でした。

3.5.0

r.history.messagesに手番ごとの道具の呼び出しと結果が入る

r = agent(question="東京の天気は?")
print(r.termination_reason)  # submit
for turn in r.history.messages:
    calls = turn["tool_calls"]
    for call, res in zip(calls.tool_calls,
                         calls.tool_call_results.tool_call_results):
        print(call.name, call.args, res.value)
# get_weather {'city': '東京'} 東京は晴れ
# submit {'answer': '東京は晴れです'} {'answer': '東京は晴れです'}

結果のキーはanswer、history、termination_reason。LLMがsubmitという道具を呼んで終わり、要求は2回でした。

dspy.ReActに道具get_weatherを渡して同じ質問をした結果。2026年11月16日、macOS 27.0.1・Python 3.13.14で、決まった手順で答える疑似サーバーを相手に、model_type="chat"で確認。

3.5.0でr.trajectoryを読むと、AttributeError: 'Prediction' object has no attribute 'trajectory'で止まります。移行ガイドは、ほかにも次の点を挙げています。

  • max_itersは道具の呼び出しの回数から、手番の数に変わる
  • 入力の欄のhistory、tools、turn_budget、出力の欄のhistory、termination_reason、submitという名前の道具は、名前を変える
  • 最適化したReActのプログラムはコンパイルし直す

以前の名前のdspy.ReActV2は3.5.0にも残っていますが、移行ガイドでは3.6で削除する予定です。

LiteLLMとOpenAIのライブラリは別に入れる

pip install dspyで入るものが大きく減りました。uvで作った空の仮想環境に入れて数えると、次のとおりです。

入るパッケージ(DSPy自身を含む)

68 → 26

3.4.1 → 3.5.0。dspy[litellm]を付けた3.5.0は68でした。

site-packagesの大きさ

223.5 → 21.9 MiB

3.4.1 → 3.5.0。LiteLLMを足さない構成なら、Dockerのイメージやサーバーレスの配布物が小さくなります。

3.5.0で入らないもの

litellm、openai

3.4.1ではlitellm 1.109.1とopenai 3.51.0が一緒に入りました。

2026年11月16日、macOS 27.0.1・Python 3.13.14・uv 0.11.32で、uv pip listとduで数えた値。

3.5.0は、LLMへの要求を同梱の軽いエンジン(lm15)で送ります。openai/、hosted_vllm/、ollama_chat/はLiteLLMなしで送れました。手元で試した範囲では、次のどれかに当たるdspy.LMはLiteLLMを通り、LiteLLMのない3.5.0では要求を送る前にImportErrorで止まりました。3.5.0のソース(dspy/clients/backend_selection.py)も、この3種類の判定でLiteLLMへ回しています。

  • lm15が扱わないモデル名(lm_studio/)
  • api_key、api_base、base_url、timeout以外の接続の設定(api_versionを付けたazure/、extra_headersやorganizationを付けたopenai/)
  • lm15が対応しない要求の引数(openai/やhosted_vllm/に付けたextra_body)

temperature、max_tokens、top_p、stop、seedはLiteLLMなしで要求に入りました。

LiteLLMを通る指定と、OpenAIのSDKを使う機能には、追加のインストールが要ります。移行ガイドの対応は次のとおりです。

  • LiteLLMを通す指定: pip install "dspy[litellm]"
  • OpenAIのSDKを使う機能: pip install "dspy[openai]"
  • OpenAI、Azure、OpenAI互換の接続先の埋め込み(dspy.Embedder): pip install "dspy[numpy,openai]"

それ以外の方式の埋め込みは、LiteLLMを入れても以前の送り方には戻らず、埋め込みを返す関数をdspy.Embedderに渡す形に書き換えると移行ガイドにあります。

lm(messages=[...])など、削除されたAPIは書き換える

LMを直接呼ぶときに会話の形で渡すlm(messages=[...])は、3.5.0では要求を送る前にTypeError: lm(messages=[...]) was removed in DSPy 3.5.で止まりました。lm("こんにちは")のように文字列で呼ぶ書き方は、3.4.1と同じく文字列のリストを返しました。会話の形で渡すときは、エラーの案内どおりdspy.lm15.Requestを作って渡します。Requestで呼ぶと、dspy.LMに付けたtemperatureやmax_tokensは要求に入りませんでした。移行ガイドも、LMの生成設定は引き継がないと書いています。同じ設定で送るには、Requestのconfigに渡します。

from dspy.lm15 import Config, Message, Request

req = Request(
    model=lm.model,  # dspy.LMのモデル名と同じにする
    system="あなたは地理に詳しい案内係です。",
    messages=(Message.user("日本の首都はどこですか"),),
    config=Config(temperature=0.3, max_tokens=321),  # LMの設定は引き継がれない
)
resp = lm(req)    # 戻り値はResponse
print(resp.text)

modelにdspy.LMと違う名前を渡すとValueError: Request.model must match LM.modelになりました。

このほか3.5.0では、dspy.ProgramOfThoughtとdspy.CodeAct、dspy.Image.from_fileとdspy.Image.from_PILがなくなっていました。移行ガイドは、前の2つをdspy.RLMで作り直し、画像はdspy.Image.from_path()やdspy.Image(pil_image)へ書き換えるよう案内しています。

3.4.1のキャッシュは3.5.0で使われない

DSPyは、同じ要求の答えをディスクにキャッシュして、2回目からはLLMへ送りません。同じキャッシュのフォルダー(環境変数DSPY_CACHEDIRで指定)を使い、ChatAdapterとmodel_type="chat"で3.4.1と同じプロンプトを送るようにして、疑似サーバーへ届いた要求を数えました。

  1. 3.4.1の1回目は1回届き、2回目は0回(キャッシュから答えた)
  2. 続けて3.5.0で同じ質問をすると、1回目は1回届いた(3.4.1のキャッシュを使わない)
  3. 3.5.0の2回目は0回

移行ガイドも、古いキャッシュは3.5.0では使われず、計算し直す前提で見積もるよう書いています。上げた直後に評価を一通り流すと、キャッシュで省けていた要求もすべてLLMへ送られ、そのぶんのAPIの料金と時間がかかります。

上げる前に直す6か所

ここまでの結果を、コードのどこを探して何に直すかの順にまとめます。

1. OpenAI互換サーバーへの送り先

openai/とapi_baseでつないでいるdspy.LM(azure/も)を探し、接続先がResponses APIに対応していなければmodel_type="chat"を足す。

2. インストールの指定

lm_studio/の指定や、api_version・extra_headers・organization・extra_bodyなどを付けたdspy.LM、OpenAI互換のdspy.Embedderを使うなら、requirementsやpyproject.tomlをdspy[litellm]、dspy[numpy,openai]に直す。

3. 最適化済みのプログラム

dspy.configure(adapter=dspy.ChatAdapter())と1のmodel_type="chat"(ChainOfThoughtはrationale_field_type=strも)で3.4.1と同じ要求を保ち、XMLへ移すかは評価の点数で決める。

4. ChainOfThoughtのreasoning

json.dumpsやisinstance(..., str)に渡している箇所を、str()かtoDict()に直す。文字列で受け取るならrationale_field_type=strを付ける。

5. ReActの結果

r.trajectoryを読む箇所をr.history.messagesとr.termination_reasonに書き換え、最適化したReActはコンパイルし直す。

6. 削除されたAPI

lm(messages=[...])をdspy.lm15.Requestに(temperatureなどはconfigに移す)、Image.from_fileをfrom_pathに、Image.from_PILをdspy.Image(pil_image)に書き換え、ProgramOfThoughtとCodeActはdspy.RLMで作り直す。

探す箇所は、プロジェクトのフォルダーで次のように検索すると見つけられます。

grep -rn --include='*.py' \
  -e 'api_base' -e 'api_version' -e 'extra_headers' -e 'organization' -e 'extra_body' \
  -e 'azure/' -e 'lm_studio/' -e 'Embedder' \
  -e '\.trajectory' -e '\.reasoning' -e '(messages=' \
  -e 'ProgramOfThought' -e 'CodeAct' -e 'from_file' -e 'from_PIL' .

直したら、3.5.0の仮想環境で評価を一通り流します。上げた直後の1回目はキャッシュが効かないので、要求の数が多い評価では、件数を絞った小さな評価から始めると料金と時間を見積もれます。

参考資料

検証環境

  • macOS 27.0.1(Apple Silicon)、Python 3.13.14、uv 0.11.32
  • dspy 3.4.1・3.5.0、dspy[litellm] 3.5.0(litellm 1.109.1)
  • 検証日: 2026年11月16日

この記事は、AIが調査と下書きを担当し、上記の環境で実際に動かして結果を確かめ、下書きとは別の担当が公開前に本文と出典を確認しています。制作と訂正の方針は編集・訂正方針で公開しています。