API 互換モデルサービスには、地味だが不可欠な役割があります。複数の公開リクエスト形式をモデルが期待する正確なプロンプトに変換し、生成されたトークンをクライアントが期待するレスポンス形状に戻すことです。deepseek-recipe は、DeepSeek V4 および V4.1 向けの変換レイヤーをパッケージ化しています。

これはモデルを実行しません。HTTP ポートを開いたり、ツールを実行したり、Web を検索したり、会話を保存したりすることもしません。この境界線を明確にしておくことが、このチュートリアルでは時間を節約します。出力はモデルの回答ではなく、推論バックエンドが消費できるレンダリング済みのプロンプトです。

Python バインディングのインストール

公式パッケージには Python 3.10 以降が必要です。

python3 -m pip install deepseek-recipe

再現可能なプロジェクトにするためには、仮想環境内にインストールし、最初の検証実行後にバージョンを固定してください。このリポジトリは 2026 年 9 月に新規公開されたばかりであり、API はまだ進化している可能性があります。Python パッケージのバージョンと、アプリケーションで選択された V4/V4.1 エンコーディングの両方を記録してください。

このパッケージは Rust クレートのファミリーによってバックされています。Python ユーザーはサービスを Rust で書き直す必要はありません。バインディングは、通常の統合に必要な変換およびエンコーディングタイプを公開します。

最小限の V4.1 会話のレンダリング

公式例に基づいた小さなスクリプトを作成します。

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "system", "content": "Answer with one short paragraph."},
        {"role": "user", "content": "Explain sparse attention to a Python developer."},
    ],
    "temperature": 0.2,
})

converted = request.convert(ConversionOptions())
encoding = DeepseekV41Encoding()
rendered = encoding.render_conversation(converted.conversation)

print(rendered.prompt)

ここには 2 つの意図的な段階があります。request.convert(...) は Chat Completions ペイロードをライブラリの共有 Conversation 表現にマップします。render_conversation(...) は V4.1 プロンプトエンコーディングを適用します。これらを分離することで、API サービスはモデル固有のトークンレイアウトにコミットする前に、異なる外部プロトコルを正規化できます。

リクエスト内のモデル文字列はクライアント向けペイロードの一部です。選択されたエンコーディングオブジェクトが、正規化された会話のレンダリング方法を制御します。任意のモデル名が自動的に重みをダウンロードまたは選択すると推測しないでください。周囲のサービスは、リクエストされたモデルを検証し、プロンプトを適切なバックエンドにルーティングする必要があります。

Try DeepSeek on MidassAI

推論接続前の確認

プロンプトの印刷はローカル開発フィクスチャでのみ行い、ユーザーデータを含む本番ログでは行わないでください。システムメッセージとユーザーメッセージが意図した順序で表現されていることを確認します。Unicode、空のコンテンツ、および複数行の例を追加します。サービスが画像やツールをサポートしている場合は、テキストのみのケースが互換性を証明すると仮定せず、それぞれ別にフィクスチャを作成します。

これはゴールデンテストを行う適切な時点でもあります。機密性の低い入力ペイロードと承認された構造期待値の小さなセットを保存します。正確なエンコード出力はパッケージのバージョン間で仕様として変更される可能性があるため、バージョンアップグレードがスナップショットを更新すべきか、レビューされるまで失敗させるべきかを決定してください。

少なくとも以下をテストします。

システムメッセージ 1 つとユーザーメッセージ 1 つ。
アシスタントのレスポンスを含むマルチターン会話。
思考モードと、公開している各 supported reasoning-effort 値。
許可されたエッジにおける temperature、top_p、および出力トークン制限。
引数を持つクライアント関数ツール。
不正なロール、コンテンツタイプ、および未サポートのオプション。

最後のグループは重要です。プロトコル互換性には拒絶互換性も含まれるからです。未サポートのフィールドを通知なく破棄するサービスは、正確なエラーを返すサービスよりもデバッグが困難です。

ライブラリの翻訳範囲

現在のスコープは、ストリーミングおよび完全レスポンスを含む Messages、Chat Completions、Responses スタイルのリクエストをカバーします。共有表現は、テキスト、画像、思考、およびクライアントツール呼び出しをサポートします。出力解析は、思考コンテンツ、ツール呼び出し、JSON オブジェクト、および停止シーケンスをカバーします。

Responses リクエストの場合、ツールネームスペースと apply_patch カスタムツールがサポートされています。これはライブラリがパッチを適用するという意味ではありません。ツール呼び出しを表現および解析するだけであり、ホストアプリケーションがツールの存在を決定し、許可を求め、実行し、その結果をモデルに返すかどうかを決定します。

V4.1 画像前処理は、画像コンポーネントと OpenCV を通じて利用可能です。画像は base64 データまたは外部 URL として入力されます。本番サービスでは、リモートコンテンツを前処理コードに渡す前に、サイズ制限、メディアタイプチェック、ダウンロードタイムアウト、およびネットワーク制限を設定する必要があります。

未サポートフィールドの明示的な処理

チェックされたリリース時点では、logprobs および top_logprobs はサポートされていません。ドキュメントコンテンツ、音声または動画、file_id によるファイル取得、n > 1 による複数完了、または暗号化された思考コンテンツも同様です。

構造化出力の期待値には注意が必要です。ライブラリは JSON オブジェクト出力を解析できますが、JSON Schema、正規表現、または厳密なツール定義を強制しません。API がそれらの保証を宣伝している場合、検証は他の場所で行う必要があります。解析された JSON オブジェクトでも、呼び出し元のスキーマに違反する可能性があります。

会話の保存もパッケージの外です。previous_response_id は以前のコンテキストを取得しません。HTTP サービスは保存された会話状態を解決し、結果のメッセージを変換に渡すか、またはフィールドを明確に拒絶する必要があります。

web_search などのサーバーツールは、レシピレイヤーがツールを実行しないためサポートされていません。クライアントがそのようなリクエストを送信した場合、意味論的な違いを文書化せずにクライアント関数呼び出しに変換しないでください。

責任範囲を曖昧にせず API サービスに追加する

クリーンなサービスパイプラインには 4 つの境界があります。

認証、レート制限、ボディサイズ制限、および公開 API 検証。
deepseek-recipe 正規化および V4/V4.1 エンコーディング。
トークンを消費し、生成されたトークンを生成する推論バックエンド。
レシピ解析、アプリケーション所有のツールオーケストレーション、および HTTP ストリーミング。

各境界の周囲でメトリクスを維持します。リクエスト変換時間、最初の生成トークンまでの時間、ツール待機時間、およびレスポンスシリアライゼーション時間は、異なる運用上の質問に答えます。これらを 1 つのレイテンシ数値に結合すると、回帰の特定が困難になります。

デフォルトでレンダリングされたプロンプトをログまたはトレーシングシステムに渡さないでください。メッセージ数、コンテンツタイプ、エンコーディングバージョン、トークン数、および変換エラーなどの安全なメタデータを記録します。サンプリングされたペイロードログ記録が避けられない場合は、オプトイン、マスク済み、アクセス制御、および短期間となるようにしてください。

このチュートリアルが不適切な場合

推論サービスを構築または適応させ、DeepSeek 固有のプロトコル変換が必要な場合は deepseek-recipe を使用してください。既存の DeepSeek 互換エンドポイントを呼び出すだけでよい場合は、そのサービスのクライアント SDK または HTTP API を使用してください。アプリケーションクライアントにプロンプトエンコーダーを追加すると、サーバー動作が重複し、アップグレードが困難になる可能性があります。

このパッケージが最も価値があるのは、まさにオールインワンサーバーではないからです。インフラストラクチャチームに、共有かつテスト可能な変換レイヤーを提供し、デプロイメント、スケジューリング、セキュリティ、およびツールを彼らの制御下に置いたままにします。成功した最初の統合は、サービングスタック全体が完成したという主張ではなく、検証されたプロンプトと未サポートフィールドのリストで終了します。

出典確認：deepseek-recipe 公式リポジトリ、2026 年 9 月 14 日アクセス。

Python で DeepSeek V4.1 向け API リクエストを変換する