DeepSeek Harness はどのようにマルチモデル API に接続するか?APIYI などのゲートウェイにおける 4 種類のプロトコル設定と使用ロジック

DeepSeek Harness はどのようにマルチモデル API に接続するか?APIYI などのゲートウェイにおける 4 種類のプロトコル設定と使用ロジック

要約:DeepSeek Harness は「カスタムモデル API」を通じて APIYI などのゲートウェイに接続できます。開発者はプロトコルごとにプロバイダーを個別に設定し、ゲートウェイが実際にサポートするモデル ID を入力し、タスクの必要に応じて別途ウェブ検索ツールを接続します。

DeepSeek Harness はサードパーティの API ゲートウェイをカスタムモデルプロバイダーとして追加でき、OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Gemini API の 4 種類のプロトコルから選択できます。そのため、1 つの Harness インスタンスから APIYI apiyi.com のような統合ゲートウェイを通じて複数ベンダーのモデルを同時に呼び出せます。接続が成功するかどうかは 4 つのポイントで決まります。プロトコルと Base URL の一致、モデル ID とゲートウェイの一致、推論および出力パラメータの互換性、そしてウェブ検索ツールの個別設計です。

以下ではまず Harness のモデル適応の仕組みと、その中でのゲートウェイの位置づけを説明し、続いて設定画面に沿ってカスタムプロバイダー設定を項目ごとに完了させ、APIYI の設定ファイルテンプレートを紹介します。その後、インターフェースは接続できても呼び出しが失敗する場合に最もよくある互換性問題とエラーコードを整理し、DeepSeek サーバー側の組み込み検索と APIYI の独立した Search / Fetch という 2 つのウェブ検索ルートを区別し、最後にマルチモデル Agent の階層設計とデプロイの推奨事項を提示します。

deepseek-harness-multi-model-api-gateway-config-ja-image-0

To Know:DeepSeek Harness マルチモデル接続の用語

用語 説明
Harness Agent の実行フレームワーク。モデル接続、ツール呼び出し、コンテキスト、セッション、タスク実行ループを担当します
API Gateway 複数のモデル API リクエストを一元的に転送・管理するゲートウェイで、外部には単一のエントリポイントを提供します
Base URL API リクエストのベースアドレス。プロトコルが異なると、アドレスのパスプレフィックスも変わります
Provider Harness に設定するモデルサービスプロバイダ。1 つのアドレス、プロトコル、キーのセットに対応します
Model ID リクエストで指定するモデルの識別子。ゲートウェイが実際に提供する名前と一致している必要があります
Chat Completions OpenAI スタイルの対話補完インターフェース。互換ゲートウェイで最もよく使われるプロトコルです
Responses API OpenAI の構造化レスポンスインターフェース。ツール呼び出しやマルチターン対話に向いています
Anthropic Messages Anthropic スタイルのメッセージインターフェース。Claude シリーズモデルのネイティブプロトコルです
Reasoning Effort モデルの思考レベルを指定するパラメータ(off、low、medium、high、max など)
Tool Calling モデルまたは Agent が外部ツールの呼び出しを判断し、その結果を後続の推論に活用します
Search / Fetch Search は Web 検索を行い結果リストを返します。Fetch は指定された Web ページの本文を取得します
API Key 認証情報。リクエストがどのモデルやインターフェースにアクセスできるかを決めます

1 なぜ DeepSeek Harness はマルチモデル API 接続に適しているのか

1.1 DeepSeek Harness のモデルプロバイダー機構

DeepSeek Harness は 2026 年 8 月 13 日に開発者プレビュー版としてオープンソース化され、MIT ライセンスを採用しています。コアアーキテクチャは「Everything is a Plugin」です。モデルアダプター、ツール、Skills、ストレージ、セッション管理はすべて交換可能なプラグインであり、モデル接続もまた、製品にハードコードされたベンダー固定の仕組みではなく、オープンな設定項目として扱われます。

モデル層では、Harness はユーザーが複数のプロバイダーを追加し、セッション内でモデルを切り替えられるようにしています。各プロバイダーには APIキー、Base URL、モデル名、API プロトコル、コンテキスト長、最大出力トークン、画像入力の可否、推論レベルを設定できます。API中継サービス、社内ゲートウェイ、自前のモデルサービスも、それぞれ独立したプロバイダーとして接続できます。

注意すべき点は、Harness が現在も開発者プレビュー段階にあり、将来のバージョンで破壊的変更が起こり得ると公式に告知されていることです。本番環境で使用する前に、バージョンを固定し、設定をバックアップしておくことをお勧めします。

1.2 DeepSeek Harness における API ゲートウェイの役割

Harness の考え方では、1つのゲートウェイはそのまま1つの Provider です。4つのフィールドが1回のリクエストの行き先を決めます。Base URL はゲートウェイのアドレスを指し、プロトコルはリクエストとレスポンスの形式を決め、APIキーは呼び出し元の身元を証明し、Model ID はゲートウェイにどのモデルへリクエストを転送するかを伝えます。

例として APIYI(apiyi.com)を見てみましょう。このプラットフォームは1つの APIキーで OpenAI、Claude、Gemini、DeepSeek などのモデルを提供し、OpenAI 互換、Anthropic ネイティブ、Gemini という3種類のプロトコル入口を開放しています。Harness ではプロトコルごとに対応するプロバイダーを作成するだけで、モデルの切り替えは Model ID の変更だけになります。ベンダーごとに個別のアカウントを申請し、キーを管理する必要はありません。

deepseek-harness-multi-model-api-gateway-config-ja-image-1


2 DeepSeek Harness でカスタムモデルプロバイダーをゼロから設定する

2.1 DeepSeek Harness のモデル設定画面を開く

Harness をローカルで起動する最短の方法は公式の npm コマンドです。事前に Node.js をインストールしておく必要があります。

npx @deepseek-ai/dsh web
# デフォルトでローカル Web UI を開きます:http://127.0.0.1:3080

画面に入ったら、設定 → モデル → モデルプロバイダーを追加 → カスタムモデル API の順にクリックすると、プロバイダー設定フォームが表示されます。公式デスクトップ版は macOS Apple Silicon 版と Windows 64 ビット版のインストーラーを提供しており、設定手順は同じです。

2.2 DeepSeek Harness プロバイダー情報の入力

設定項目 役割 入力のポイント
Provider ID プロバイダーの一意識別子 必ず小文字で指定します。作成後は名前を変更できません(例:apiyi)
表示名 モデルメニューに表示される名前 「APIYI OpenAI 互換」などと記述できます
API プロトコル リクエストとレスポンスの形式 Base URL に対応させます(2.3 参照)
Base URL API サービスのアドレス バージョンのプレフィックスに注意してください(2.4 参照)
APIキー 認証情報 認証情報ファイルに保存され、画面にはマスクされたプレビューのみ表示されます
Model ID 実際に呼び出すモデル名 ゲートウェイのモデルリストと完全に一致させます
Context Window / Max Output Tokens コンテキストと最大出力長 モデルの実際の仕様に従って入力します
Input Type テキストまたは画像の入力 視覚モデルのみ画像にチェックを入れます
Reasoning Effort 思考レベルとパラメータのマッピング モデルが実際にサポートする段階のみを追加します

Provider ID を後から変更できないのは、モデル設定・過去の会話・認証情報の参照がすべてこの ID を指しているためです。変更が必要な場合は、先に新しいプロバイダーを作成してから、古いものを削除してください。

フォームの「利用可能なモデルを取得」ボタンは、ゲートウェイからモデルリストを読み取ろうとします。ゲートウェイが標準的なモデルリストを提供していない場合や、返される形式が Harness の認識範囲外である場合は、Model ID を手動で追加しても同じ結果になります。

2.3 DeepSeek Harness の API プロトコルを選択する

Harness のカスタムモデル API は4つのプロトコルをサポートしています。OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Gemini API です。1つのプロバイダーは1つのプロトコルにしかバインドできません。同じゲートウェイが3種類のプロトコルエントリーポイントを公開している場合、3つのプロバイダーを作成する必要があります。

プロトコルの選択はモデルファミリーに従います。GPT、DeepSeek、および大多数の中国製モデルは、OpenAI Chat Completions を使うのが最も安定しています。Claude シリーズは Anthropic Messages を選ぶことでネイティブ機能を保持できます。Gemini シリーズは Gemini API を使用します。Responses プロトコルは、構造化レスポンスやツール呼び出しが必要なシーンに適しており、ゲートウェイと対象モデルの両方がこのインターフェースをサポートしていることが前提です。

2.4 APIYI で DeepSeek Harness インスタンスを設定する

APIYI 公式が示しているプロトコルと Base URL の対応関係は次のとおりです。

プロトコル APIYI Base URL 対応モデル 利用可能なプラットフォーム
OpenAI 互換(Chat Completions) https://api.apiyi.com/v1 GPT、DeepSeek など APIYI apiyi.com、各ベンダー公式 API
Anthropic ネイティブ https://api.apiyi.com Claude シリーズ APIYI、Anthropic 公式
Gemini https://api.apiyi.com/v1beta Gemini シリーズ APIYI、Google 公式

Anthropic プロトコルはルートドメインを使用し、アダプターが後続のパスを自動的に結合します。ルートドメインの後に /v1 を余分に書くと、パスが重複して 404 が返される可能性があります。Responses プロトコルの接続方法は、APIYI の Responses API ドキュメントを参照して確認したうえで入力してください。

UI での設定のほか、Harness は設定ファイルの手動編集にも対応しています。ファイルの場所は $DSH_HOME/profiles/web/cordis.patch.yml です。以下は、公式の設定構造に沿って作成した APIYI の OpenAI 互換プロバイダーのテンプレートです。

- id: llm-pi-ai
  config:
    providers:
      apiyi:
        apiKeyEnv: APIYI_API_KEY          # 環境変数からキーを読み取る
        api: openai-completions           # OpenAI Chat Completions プロトコル
        baseURL: https://api.apiyi.com/v1 # APIYI の OpenAI 互換エントリーポイント
        models:
          - id: MODEL_ID_FROM_APIYI       # アカウントで実際に利用可能なモデル ID に置き換える

使用手順は次のとおりです。

  1. 環境変数 APIYI_API_KEY を設定します;
  2. MODEL_ID_FROM_APIYI を、APIYI コンソールで実際に利用可能なモデル名に置き換えます;
  3. 設定を保存し、Harness のモデルセレクターで apiyi プロバイダーと対応するモデルを選択します;
  4. 簡単な会話を一度実行して、インターフェースが正常に動作することを確認します。

このテンプレートは公式の設定構造を示したものです。モデル名は、自分のアカウントで呼び出せるリストを基準にしてください。モデル設定の変更は通常、次回のリクエスト時に反映され、Web UI の再起動は不要です。UI からの設定は、日常的にモデルを追加したりキーを変更したりするのに適しています。設定ファイルは、互換パラメータ、推論モード、タイムアウト、リトライなどの高度な設定を調整するのに適しています。

Harness に接続する前に、スクリプトで APIキーと Model ID を個別に検証し、「ゲートウェイが利用可能か」と「Harness の設定が正しいか」という2つの問題を切り分けてトラブルシューティングすることをおすすめします。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1"  # APIYI apiyi.com の OpenAI 互換エントリーポイント
)

resp = client.chat.completions.create(
    model="MODEL_ID_FROM_APIYI",  # Harness に記入する Model ID と一致させる
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
    max_tokens=100
)
print(resp.choices[0].message.content)

🚀 クイックスタートのヒント:新規ユーザーは APIYI apiyi.com で登録すると無料のテスト枠を受け取れます。まず上記のスクリプトでモデル ID が利用可能か確認し、その後 Harness の設定に書き込むと、全体のトラブルシューティング時間を大幅に短縮できます。


3 DeepSeek Harness で接続できるのに、モデル呼び出しが失敗する理由

Harness の公式ドキュメントでは、API アドレスとキーが正しくても、ゲートウェイがリクエストを拒否することがあると明記されています。原因は、互換インターフェースごとにメッセージロール、出力長、思考パラメータへの要件が異なる点にあります。以下の 3 つの compat パラメータはこうした問題を解決するためのもので、インターフェースが実際に返すエラーに応じて必要なものを有効にしてください。

3.1 Developer ロールの互換設定

新しい OpenAI 仕様では role: developer が導入されましたが、一部の互換ゲートウェイは system しか認識しません。「すべてのリクエストが失敗する」あるいは「推論モデルだけが失敗する」という状況では、developer ロールを無効にできます。

compat:
  supportsDeveloperRole: false

このオプションを有効にすると、アダプターがリクエスト内のロールの扱いを調整し、ゲートウェイが受け入れ可能な形式に合わせます。

3.2 最大出力パラメータの互換設定

OpenAI の新しいインターフェースでは最大出力を max_completion_tokens で表しますが、一部のゲートウェイは従来の max_tokens しか受け付けません。意味は同じでもフィールド名が異なると、パラメータ検証で失敗します。対応する設定は次のとおりです。

compat:
  maxTokensField: max_tokens

3.3 DeepSeek 思考モードの互換設定

一部の DeepSeek モデルは思考がデフォルトで有効になっています。Harness で推論レベルを off にしても、互換プロトコルによっては推論パラメータを省略するだけなので、モデルはデフォルト動作のまま思考を続けてしまい、「off にできない」状態になります。そこで公式は DeepSeek 専用の思考フォーマットを用意しています。

compat:
  thinkingFormat: deepseek

有効にすると、思考をオフにするときは {"thinking": {"type": "disabled"}} を、オンにするときは {"thinking": {"type": "enabled"}} を明示的に送信します。公式の例は、OpenAI 互換ゲートウェイの背後の DeepSeek V4 モデルを対象としています。マルチモデルゲートウェイでは、DeepSeek モデルにのみこのパラメータを設定し、GPT や Claude などのモデルはデフォルトのままにできます。

推論レベルについては、Harness は UI 上の off、low、medium、high、max を、API が実際に受け付けるパラメータ値へマッピングできます。モデルが実際にサポートする段階だけを設定に含めることで、ユーザーが無効な段階を選んでリクエストがエラーになるのを防げます。3 つの互換パラメータをまとめた完全な例は次のとおりです。

- id: llm-pi-ai
  config:
    providers:
      apiyi:
        apiKeyEnv: APIYI_API_KEY
        api: openai-completions
        baseURL: https://api.apiyi.com/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: MODEL_ID_FROM_APIYI

3.4 DeepSeek Harness のよくあるエラーを素早く切り分ける

エラー/現象 考えられる原因 対応方法
MISSING_CREDENTIAL キーが未設定 APIキーと環境変数名を確認する
UNKNOWN_MODEL モデル ID が未登録 プロバイダー配下に正しいモデル ID を追加する
HTTP 401 キーが無効、または権限不足 キーの内容と所属グループを照合する
HTTP 404 Base URL のパスが誤り プロトコルとバージョンプレフィックス(/v1、ルートドメイン、/v1beta)を確認する
モデル一覧が空 ゲートウェイが標準のモデル一覧インターフェースに対応していない モデル ID を手動で追加する
すべてのリクエストが失敗 ロールやパラメータの形式が衝突している compat の互換パラメータを確認する
推論モデルだけが失敗 Developer ロールが非互換 supportsDeveloperRole: false を設定する
off で思考を止められない モデルがデフォルトで思考を有効にしている thinkingFormat: deepseek を設定する
検索インターフェースが 503 を返す トークンのグループにツール権限がない default または svip グループのトークンに変更する
会話は正常だがネット連携が使えない 検索ツールが未統合、またはプロトコル非対応 ツールの機能とクライアント設定を確認する

最初の 8 項目は Harness 公式の設定ドキュメントに基づくもので、グループ関連の問題は APIYI 公式ドキュメントに由来します。切り分けは上から下へ進めるのがおすすめです。まず認証情報を確認し、次にモデル ID、その後にパス、最後にパラメータの互換性を確認します。


4 DeepSeek Harness にインターネット検索機能を追加する

4.1 モデル内蔵検索と独立した検索 API を区別する

通常の会話呼び出しが成功しただけでは、APIキーが有効で、モデルIDが正しく、会話プロトコルが基本的に互換であることしか証明できません。インターネット検索機能には、モデルが対応ツールをサポートしていること、リクエストでツールを正しく宣言していること、APIサービスがそのツールプロトコルをサポートしていること、Harnessがツール応答を処理できること、あるいは開発者がアプリケーション側で検索を個別に統合していることが必要です。したがって、チャットの成功とインターネット検索の成功は、2つの独立した検証ステップです。

DeepSeek の環境におけるインターネット検索機能には、2つの技術ルートがあります:

deepseek-harness-multi-model-api-gateway-config-ja-image-2

観点 ルートA:モデル内蔵のサーバー側ツール ルートB:独立した Search / Fetch API
呼び出し方法 会話リクエスト内で deepseek_web_search、deepseek_read_url を宣言 プログラムが能動的に /v1/tools/search、/v1/tools/fetch をリクエスト
検索を決定する主体 モデルが自律的に判断 開発者または Agent のツールロジック
ツールの実行 DeepSeek サーバー側が検索とコンテキスト結合を実行 クライアントが結果を受け取って独自に処理
対象モデル 公式発表では deepseek-flash を明示的に対象 モデルに依存せず、任意のモデルが結果を再利用可能
課金基準 実際の検索語数、取得したウェブページ数などに基づいて課金 成功したリクエスト回数に基づいて課金され、モデルの Token を消費しない
現在利用可能なチャネル DeepSeek 公式 API DeepSeek 公式 API、APIYI

4.2 モデル内蔵検索の仕組み

2026年11月13日、DeepSeekはアプリの背後にある複数のアプリケーション機能を公開しました。そのうちWeb検索とリンク読み取りは、サーバー側ツールとして提供されます。リクエストのツールリストに宣言するだけで利用できます。

[
  {"type": "deepseek_web_search", "name": "deepseek_web_search"},
  {"type": "deepseek_read_url", "name": "deepseek_read_url"}
]

宣言すると、モデルが自分でネット接続の要否を判断し、検索語を生成します。そしてDeepSeekのサーバー側が検索を実行し、出典引用付きの回答を返します。思考モードを有効にすると、検索はマルチステップのプロセスに進化します。モデルは複数のキーワードで検索し、Webページを開き、ページ内検索を行い、さらにクロスチェックすることもできます。公式ドキュメントによると、ツール呼び出しは最大で約20回行われた後に回答が生成されます。deepseek_read_url が認識するのは最後のユーザーメッセージに含まれるURLのみで、最大10個の異なるリンクが対象になります。

開発者は引き続き、返却されるコンテンツブロック、引用情報、ストリーミングイベント、マルチターンの履歴を処理する必要があります。公式発表によれば、この会話レベルで完結するツール統合は deepseek-flash(DeepSeek-V4.1-Flash)が担っています。APIYIのドキュメントの説明では、HarnessやClaude Codeなどのクライアントからゲートウェイ経由でこの種の内蔵検索を呼び出すための互換対応は、今後の計画に含まれています。現時点でルートAを利用するには、DeepSeekの公式APIに直接接続する必要があります。

4.3 APIYI 独立 Search / Fetch 接続

APIYI は 2026 年 10 月 21 日に DeepSeek Search & Fetch の独立ツールインターフェースを公開しました。それぞれ deepseek-search と deepseek-fetch に対応します。Search は構造化された検索結果を返し、Fetch は指定した Web ページを取得して Markdown 本文を返します。リクエストにモデル ID を渡す必要はなく、モデルの Token も消費しません。課金は成功した呼び出し回数に応じて行われます。

以下の例では、まず検索を実行し、そのあとで 1 位の Web ページを取得します:

import os
import requests

BASE = "https://api.apiyi.com/v1/tools"  # APIYI 独立ツールインターフェース
headers = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}

search = requests.post(
    f"{BASE}/search",
    headers=headers,
    json={"query": "DeepSeek Harness 插件", "count": 5},
    timeout=60,
)
search.raise_for_status()
results = search.json()["results"]

if results:
    url = results[0]["url"]
    fetch = requests.post(
        f"{BASE}/fetch",
        headers=headers,
        json={"url": url},
        timeout=60,
    )
    if fetch.ok:
        print(fetch.json()["content"])

トークングループには特に注意が必要です。default と svip グループはこの 2 つのインターフェースを呼び出せますが、ClaudeCode グループのトークンでは直接呼び出せず、ドキュメントには 503 が返る事例が記録されています。APIYI のドキュメントにある自己テストでは、Search が 5 件の結果を返すのに約 1.8 秒かかり、20 件の同時リクエストがすべて 200 を返しました。Fetch は到達不可能なページにアクセスした場合、失敗を返し課金されません。これらのデータはプラットフォーム自身のテストによるもので、実際のパフォーマンスはネットワークや対象サイトの影響を受けます。価格については、ドキュメントにサイト内価格として 1000 回あたり $0.90 と記載されており、チャージ時のボーナスを加えると実質的な支払額はさらに低くなります。詳細はコンソールでご確認ください。

Harness 内の Agent がこのロジックを自律的に利用できるようにするには、ツールプラグインとしてカプセル化する必要があります。Harness のプラグインは TypeScript で書かれ、コンテキストオブジェクト ctx を通じてツールを登録します。プラグインのアンロード時には、フレームワークが登録済みのツールとイベントを自動的にクリーンアップします。カプセル化の際は、search と fetch を 2 つの独立したツールとして登録し、モデルがまず結果リストを取得してから、どのページを取得するかを決められるようにするのがおすすめです。

💡 技術的なヒント:独立した Search / Fetch はモデルから切り離されているため、同じ検索結果を GPT、Claude、DeepSeek など異なるモデルに渡して処理させられます。APIYI apiyi.com を使えば、1 つのキーでモデル呼び出しと検索ツールをまとめて管理でき、Harness 内で同じ資料に基づく異なるモデルの回答品質を比較しやすくなります。

5 DeepSeek HarnessのマルチモデルAgentはどう設計すべきか

5.1 タスクに応じて異なるモデルを選択する

マルチモデル接続の価値は、タスクごとにモデルを割り当てられることにあります。コーディングAgentにはコードに強いモデルを選べます。文書整理や要約・書き換えのような高頻度タスクには、低コストのモデルが適しています。スクリーンショット分析やグラフ理解には、画像入力に対応した視覚モデルを選び、Input Typeで画像にチェックを入れる必要があります。

DeepSeek公式モデルを例にすると、DeepSeek-V4.1-Flashは画像理解に対応していますが、DeepSeek-V4-Proは対応していません。両者の価格も数倍の差があります。Harnessでこれらを同じプロバイダー配下の2つのModel IDとして設定し、タスクに応じて会話中に切り替えれば、効果とコストの両立を図れます。

5.2 DeepSeek Harnessのモデル呼び出しと検索機能を階層的に管理する

deepseek-harness-multi-model-api-gateway-config-ja-image-3

推奨する構成は3層に分かれます。実行層はHarnessがタスクループ、コンテキスト圧縮、プラグインの読み込み、権限管理を担います。モデル層はAPIゲートウェイがプロトコル変換、モデルルーティング、課金を担います。ツール層は独立したSearch / Fetchなどのインターフェースが外部情報を提供します。3層はそれぞれ差し替え可能で、モデルを変更する場合はModel IDだけを変え、検索サービスを変更する場合はツールプラグインだけを変えればよく、実行ロジックは変わりません。

階層化にはセキュリティ上の利点もあります。テンセントの朱雀(Zhuque)研究所によるHarnessの制御環境下での評価では、Webページ、ファイル、Skillsなどの信頼できないコンテンツが、間接プロンプトインジェクションを通じてAgentの動作に影響を与え得ることが示されています。ツール層と実行層を分離すれば、検索結果がコンテキストに入る前や、機密性の高いツールを実行する前に、共通のフィルタリングと確認ステップを追加できます。

5.3 DeepSeek Harnessの実運用における導入推奨事項

  1. モデル設定:1つのプロトコルに対して1つのプロバイダーを割り当て、Provider IDは小文字で一度決めたら変更しないようにします。モデルIDは必ずゲートウェイのコンソールからコピーしてください。
  2. キー管理:Harnessはキーを$DSH_HOME/.credentials.yamlに保存します。設定ファイルでは環境変数のみを参照し、平文のKeyが共有設定やコードリポジトリに混入しないようにします。
  3. 互換性テスト:新しいモデルを接続するたびに、通常の会話、思考の無効化、長い出力、画像入力の順に検証し、エラーメッセージに応じてcompatパラメータを有効化します。
  4. ツール呼び出し:プラグイン数を制御します。コミュニティの報告では、十数個以上のプラグインをインストールするとコンテキストのオーバーフローやToken消費の増加が発生する可能性があるため、検索ツールは説明を簡潔に保つほうが安定します。
  5. コスト記録:モデルのTokenとツール呼び出しは別々に課金されるため、ゲートウェイの管理画面でそれぞれ集計することをおすすめします。APIYI apiyi.comのコンソールではKeyごとに使用量を確認できるので、Agentごとに独立したKeyを割り当ててコストの帰属を明確にするのに適しています。

また、Harnessをアップグレードする前に、$DSH_HOME配下の設定をバックアップしてください。コミュニティでは、バージョンアップ後にサードパーティ製プラグインの設定が失われ、復元に数時間かかった事例が報告されています。


よくある質問(FAQ)

Q1:DeepSeek Harness では DeepSeek のモデルしか使えないのでしょうか?

Harness はカスタムモデル API 経由で、4 種類のプロトコルのいずれかに対応した任意のサービスに接続できます。OpenAI、Claude、Gemini シリーズのほか、各種 API ゲートウェイや自前のモデルサービスも含まれます。DeepSeek の公式モデルは、あくまで選択肢のひとつにすぎません。

Q2:同じゲートウェイなのに、なぜ複数のプロバイダーを作る必要があるのですか?

Harness では、1 つのプロバイダーは 1 つのプロトコルにのみ紐づける仕様です。APIYI は OpenAI 互換、Anthropic、Gemini の 3 つの入口を同時に公開しているため、GPT・Claude・Gemini をそれぞれネイティブプロトコルで呼び出すには、プロバイダーを 3 つ作成する必要があります。Base URL はそれぞれ `/v1`、ルートドメイン、`/v1beta` になります。

Q3:自分がどのモデル ID を入力すべきかは、どう確認すればよいですか?

まず「利用可能なモデルを取得」機能を試してください。読み取れない場合は、APIYI apiyi.com のコンソールにあるモデル一覧から正確な名称をコピーして手動で追加します。モデル ID は大文字・小文字やバージョンのサフィックスまで区別されるため、少しでも違いがあると UNKNOWN_MODEL やゲートウェイのエラーが発生します。

Q4:APIYI 経由で接続した場合、deepseek_web_search をそのまま使えますか?

現在 APIYI は DeepSeek の独立した Search / Fetch インターフェースに対応していますが、Harness などのクライアント経由でモデル内蔵の検索を呼び出す互換対応はまだ計画段階です。現時点では、APIYI の `/v1/tools/search` と `/v1/tools/fetch` を Agent ツールとしてラップする方法をおすすめします。内蔵検索が必要な場合は、DeepSeek 公式 API に直接接続してください。

Q5:検索インターフェースが 503 を返すのに、対話はまったく正常なのはなぜですか?

最もよくある原因はトークンのグループです。ClaudeCode グループのトークンでは独立したツールインターフェースを直接呼び出せないため、default または svip グループの Key に切り替えれば解決します。APIYI apiyi.com の管理画面で、検索ツール専用に該当グループのトークンを別途作成し、モデル呼び出し用の Key と分けて管理することもできます。

Q6:DeepSeek Harness のマルチモデル接続には、どのような制約がありますか?

Harness はまだ開発者プレビュー版であり、設定構造がバージョンによって変わる可能性があります。また、各ゲートウェイで Responses、推論パラメータ、ツールプロトコルのパススルー対応度が異なるため、モデルごとに個別に検証する必要があります。プラグインが多すぎるとコンテキストとトークンのコストが増大し、複雑なタスクの成果品質はプラグインの設定と実行プロセスの管理にも左右されます。


まとめ

DeepSeek Harness が提供するオープンモデル適応メカニズムにより、1つの Agent フレームワークから統一ゲートウェイ経由で複数ベンダーのモデルを呼び出せます。実装の際には、以下のポイントを押さえておきましょう。

  1. プロトコルでプロバイダーを決める:1つのプロトコルにつき1つの Provider を作成し、Base URL のバージョンプレフィックスとプロトコルを厳密に対応させます。
  2. モデル ID はゲートウェイからそのままコピー:コンソールからコピーします。一覧が読み込めない場合は手動で追加しましょう。
  3. 互換パラメーターはエラーに応じて有効化:developer ロール、max_tokens フィールド、DeepSeek の思考フォーマットという3項目で、「接続はできるが使えない」問題の大半をカバーできます。
  4. ネットワーク連携機能は個別に計画:内蔵検索は DeepSeek 公式 API を利用し、独立した Search / Fetch はゲートウェイ経由で呼び出してツールとしてカプセル化できます。
  5. レイヤーの分離とガバナンス:実行レイヤー、モデルレイヤー、ツールレイヤーを分け、APIキー、バージョン、コストをそれぞれ個別に管理します。

まずは1つのモデルで「スクリプト検証 → Harness 設定 → 簡単な対話」を一通り動かしてみて、その後でより多くのモデルや検索ツールを段階的に追加していくことをおすすめします。APIYI apiyi.com で無料のテスト枠を受け取り、1つの Key でマルチモデルと Search / Fetch の全体検証を完了するのがおすすめです。


📚 参考資料

  1. DeepSeek Harness モデル設定ドキュメント:カスタムプロバイダーのフィールドと compat 互換パラメーター
  2. リンク: deepseek-harness.github.io/deepseek-harness/guide/providers
  3. 説明: supportsDeveloperRole、maxTokensField、thinkingFormat の公式解説

  4. DeepSeek Harness GitHub リポジトリ:ソースコード、Releases、起動方法

  5. リンク: github.com/deepseek-ai/deepseek-harness
  6. 説明: バージョンアップデートと開発者プレビュー段階の説明

  7. DeepSeek ネットワークツールドキュメント:deepseek_web_search と deepseek_read_url

  8. リンク: api-docs.deepseek.com/zh-cn/guides/web_tools/
  9. 説明: 内蔵検索の宣言方法、制限、課金ルール

  10. APIYI Base URL 設定ガイド:3つのプロトコルパスの説明

  11. リンク: help.apiyi.com/apiyi-base-url-v1-claude-gemini-endpoint-config-guide.html
  12. 説明: /v1、ルートドメイン、/v1beta の利用シーン

  13. APIYI DeepSeek Search & Fetch ドキュメント:独立ツールのインターフェースとグループ要件

  14. リンク: docs.apiyi.com/api-capabilities/deepseek-search-fetch/overview
  15. 説明: リクエストパラメーター、トークングループ、課金の説明

著者: APIYI 技術チーム
技術交流: 設定中に問題が発生した場合は、APIYI apiyi.com のトップページからお気軽にお問い合わせください。その他のインターフェースの説明は docs.apiyi.com のドキュメントセンターをご覧ください。

関連記事

類似投稿