Platform Docs
Try DatumoEval

Application API 連携

Application の Module と Version を実際の AI サービス API に接続し、マルチターン会話、レスポンスのマッピング、トークン使用量・コストを設定する方法を説明します。

はじめる前に

①連携するとできること

連携が完了すると、評価、レッドチーミング、モニタリングがサービス API を直接呼び出します。これにより、評価・攻撃・観測のジョブを実行できるようになります。先に Application の作成を済ませてください。

連携は 設定 > Application > Agent Connection で行います。左メニュー下部の Application Setting をクリックすると開きます。画面構成は Application の作成の Agent Connection 画面を参照してください。

②連携の手順

連携は以下の順序で行います。ステップ 1 で決めた Key 構成が、以降のすべてのステップの基準になります。

ステップ内容
1. Module の設定評価する Module の Input Key と Output Key を決めます。
2. Version の設定Before と After を比較する Version を登録します。
3. Version ごとの API 連携Version ごとに API の URL と送信内容を入力し、テストします。
4. マルチターン API 連携チャットボットのように過去の会話もあわせて送る API の場合のみ設定します。
5. Output Key のマッピングレスポンスから評価する値を選び、必要に応じてコスト計算を設定します。

1. Module の設定

Module は Application の機能単位です。評価する機能に合った Module Type を選びます。各 Module には次の Key があります。

Key意味
Input KeyModule に渡される入力
Output KeyModule の実行後に生成される出力

①1-1. Module の作成

  1. + New Module をクリックします。

  2. Module Type を選択します。複数の Module Type を選択できます。

  3. Add をクリックします。

②1-2. Module の編集

  1. Module 右上の編集(鉛筆)アイコンをクリックします。

  2. Module 名、Input Key、Output Key を編集します。

  3. 必要に応じて Key を追加します。

ボタン動作
+Add Input KeyInput Key を追加します。
+Add Output KeyOutput Key を追加します。

Input Key または Output Key を 1 つでも編集すると、この Application のすべての Version 設定を最初からやり直す必要があります。

③1-3. Module の削除

  1. Delete ボタンをクリックします。

  2. 入力欄に Delete module と入力します。Delete ボタンが有効になります。

  3. Delete をクリックします。Module が削除されます。

  1. 1-1Module の確認

    1. Agent Connection の Module List で Module と Key を確認します。
  2. 1-2Module の追加・編集

    1. + New Module で追加します。
    2. Module カードの編集ボタンで名前と Key を変更します。
    3. Save をクリックします。

    Key を 1 つでも編集すると、この Module のすべての Version 設定をやり直す必要があります。

  3. 1-3Module の削除

    1. 編集ダイアログの Delete をクリックします。

2. Version の設定

1 つの Application に複数の Version を持たせることができます。プロンプト、モデル、検索方式が変わるたびに新しい Version を登録します。そうすれば、同じ評価基準で Before と After を比較できます。

Version の作成方法は Application の作成の Version 作成ステップに従います。Application の Version と Module の Version は、どちらも以下のステップ 3〜5 と同じ方法で設定します。

Version 運用のヒント

  • 1 つの変更に 1 つの Version: 複数の要素を一度に変えると、どの変更がスコアに影響したのかわからなくなります。
  • 命名規則の統一: Version の命名規則をあらかじめ決めておくと、Dashboard で時系列に沿って比較しやすくなります。
  • 削除ではなく無効化: 失敗した Version は無効化して残しておきます。後で同じ問題が再発していないかを確認したり、結果を再現したりするときに使います。

3. Version ごとの API 連携

評価、攻撃、観測を実行するには、Version ごとに呼び出し可能な API を接続する必要があります。API の URL は Version ごとに個別に設定できます。そのため、同じ評価セットを複数の環境(例:staging、production、新しいモデル)に一度に適用できます。

①3-1. 連携情報の入力

  1. Version の行で API Integration をクリックします。
  2. 以下の情報を入力します。
項目入力内容
API URL呼び出す API の URL
Methodリクエスト方式。通常はデフォルトの POST のまま使います。
Request Header認証キーなどのヘッダー。Content-Type: application/json はあらかじめ入力されています。
Request ParameterURL の後ろに付ける値。必要な場合のみ入力します。
Request Body送信する内容(JSON)。3-2 で説明します。

Authorization、x-api-key などの API キーは、保存すると sk-****6789 のようにマスクされます。評価時には元の値が使われます。キーを変更するには、マスクされた欄をクリックして新しい値を入力します。

②3-2. Request Body の作成

  1. リクエスト本文を JSON で作成します。
  2. ステップ 1 で決めた Input Key を {{key_name}} の形式で挿入します。評価時に Benchmark Set の実際の値に置き換えられます。
{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "{{user_query}}" }
  ],
  "temperature": 0.2
}

上の例では、{{user_query}} は実行時に各 Benchmark 行の user_query の値に置き換えられます。

ダイアログ下部の Required variables にある変数のみ使用でき、すべてを 1 回以上使う必要があります。名前は Input Key と完全に一致している必要があります。

③3-3. 接続テスト

  1. 右側の Test Connection に、変数ごとにサンプル値を入力します。
  2. Test Connection をクリックします。
  3. レスポンスが正しく返ってくるか確認します。

認証エラーや形式エラーをここで事前に見つけておけば、評価中に大量に失敗するのを防げます。

④3-4. 保存

ボタン使うタイミング
Save Draftまだ入力が終わっていないときに、ここまでの入力内容を一時保存します。
Go to Output Mapping入力が終わったら、次のステップ(5. Output Key のマッピング)に進みます。

保存せずにダイアログを閉じると、保存するかどうかを確認するダイアログが表示されます。

  1. 3-1連携ダイアログを開く

    1. Version 行の赤い API Integration をクリックすると、Set up Version ダイアログが開きます。
    2. Version Name を確認します。
  2. 3-2URL と Method

    1. URL に呼び出す API の URL を入力します。
    2. Method を選びます。通常は POST です。

    URL が空欄、または形式が正しくない場合は赤いメッセージが表示されます。

  3. 3-3Request の設定

    1. 案内ボックスで、この Application の入力変数を確認します。
    2. 必要に応じて Request Header に認証キーを入力します。
    3. Request Body に変数を {{key_name}} の形式で挿入します。

    ダイアログ下部の Required variables をすべて 1 回以上使う必要があります。

  4. 3-4接続テスト

    1. 右側の Test Connection に、変数ごとにサンプル値を入力します。
    2. Test Connection をクリックし、レスポンスを確認します。
  5. 3-5保存

    1. まだ入力が終わっていなければ Save Draft をクリックします。
    2. 入力が終わったら Go to Output Mapping をクリックします。

4. マルチターン API 連携

チャットボットのように過去の会話もあわせて送る必要がある API は、Multi-turn をオンにして連携します。質問を 1 つだけ送る API であれば、このステップは飛ばしてください。

①4-1. Multi-turn をオンにする

  1. API 連携ダイアログ左側の Multi-turn トグルをオンにします。
  2. Request Body に以下のデフォルト例が入力されます。
{
  "messages": [
    ...{{chat_history}},
    { "role": "user", "content": "" }
  ]
}
  • ...{{chat_history}} の位置に過去の会話が入ります。Request Body に必ず 1 回入れる必要があります。
  • そのすぐ後のオブジェクトが、今回のターンで送る質問です。
  • "content" は空です。4-2 で入力変数を選ぶと、"{{query}}" のように入力されます。

Multi-turn では Request を 1 つしか使いません。Request 2 以降を作成した状態でオンにすると、Request 2 以降は削除されます。

②4-2. Turn Definition の設定

Turn Definition で、過去の会話の 1 ターンをどの値で埋めるかを決めます。デフォルト例を使う場合は、{{content}} 行の 2 つの欄を埋めるだけで済みます。

項目User Turn(ユーザーの発話)Assistant Turn(エージェントの回答)
{{role}}user(自動入力)assistant(自動入力)
{{content}}入力変数を選択(例:{{query}})レスポンス内で回答があるパスを入力(例:result.answer)
  1. {{content}} 行の User Turn で入力変数(例:{{query}})を選びます。
  2. 同じ行の Assistant Turn に、エージェントの回答があるパスを入力します。パスがわからない場合は Pick from response を押し、レスポンスから回答を選んで Select をクリックします。
  3. フィールドがさらに必要な場合は + Add Variable で追加します。Request Body にも自動で挿入されます。

空欄が 1 つでもあると、次のステップに進めません。

③4-3. 2 ターンの接続テスト

Multi-turn の Test Connection には Turn 1、Turn 2 の欄があります。

  1. Turn 1 に最初の質問、Turn 2 に続きの質問を入力します。
    (例:私の名前はダトゥモです。 → 私の名前は何でしたか?)
  2. Test Connection をクリックします。
  3. Turn 2 のレスポンスが Turn 1 の内容を覚えているか確認します。

2 つのターンがどちらも成功して、はじめてテスト完了とみなされます。失敗したターンは、結果にマウスを合わせて再試行アイコンから再実行します。

  1. 4-1Multi-turn をオンにする

    1. Multi-turn トグルをオンにします。Request Body に ...{{chat_history}} のデフォルト例が入力されます。
    2. Turn Definition で、過去の会話の 1 ターンを埋める値を決めます。

    Multi-turn では API Chaining を使用できません。


5. Output Key のマッピング

API レスポンスのどの値を評価するかを指定するステップです。Go to Output Mapping を押すとダイアログが開きます。

①5-1. レスポンスパスの入力

  1. Output Key ごとに、レスポンス内のパスを入力します。パスがわからない場合は Pick from response でレスポンスから値を選んで入力します。
Output Keyパスの例
answerresponse_1.choices[0].message.content
retrieved_docsresponse_1.context.documents
  1. パスの下の Extracted Value に表示された値が正しいか確認します。
  2. Save をクリックします。
  • パスが間違っていると赤いメッセージが表示され、保存できません。
  • 接続テストを行っていない場合は、保存時にテストするかどうかを確認されます。

誤ってマッピングされた Key は、すべての評価結果を不正確にします。スコアが変わった理由を追跡できなくなります。

②5-2. トークン使用量とコスト(任意)

コストを確認したい場合のみ設定します。設定すると、Run Report の Usage タブとエージェントシミュレーションでコストが表示されます。

  1. 同じダイアログ下部の Token Usage & Cost で、Input Tokens、Output Tokens のパスを入力します。Pick from response で選んでもかまいません。
  2. Input token cost ($)、Output token cost ($) に 100 万トークンあたりの価格を入力します。
  3. 下のボックスに推定コストが表示されたら、Save をクリックします。

よく使われるトークンパスは以下のとおりです。

プロバイダー入力トークン出力トークン
OpenAI、vLLM、Ollama(OpenAI 互換)usage.prompt_tokensusage.completion_tokens
Anthropic、OpenAI Responsesusage.input_tokensusage.output_tokens
GeminiusageMetadata.promptTokenCountusageMetadata.candidatesTokenCount
  • 後で設定するには Version 行の Go to Setting を、修正するには Edit Token を押します。
  • すでに実行した評価のコストは、Run Report で設定すると再計算されます。評価レポートを参照してください。
  1. 5-1レスポンスパスの入力

    1. 左側で Test Connection を実行し、レスポンスを取得します。
    2. Output Key ごとに Pick from response をクリックします。
    3. レスポンスから値を見つけて Select をクリックします。
    4. Extracted Value で値を確認します。

    パスが間違っていると赤いメッセージが表示され、保存できません。

  2. 5-2トークン使用量とコスト(任意)

    1. Input Tokens、Output Tokens のパスを入力します。
    2. 100 万トークンあたりの単価を入力し、推定コストを確認します。
  3. 5-3保存

    1. Save をクリックします。Version が Ready 状態になります。

6. ポータルからモデル・Agent を読み込む(Enterprise)

社内モデルポータルを接続した Enterprise の Organization は、API を直接入力せずに、ポータルに登録されたモデルや Agent を読み込んで Version を作成できます。+ New Version を押すと、まず接続方式を選ぶ Set up Version ダイアログが開きます。

方式説明
Load Modelポータルに登録されたモデルを読み込みます。
Load Agentポータルに登録された Agent と、その Agent の Version を読み込みます。
Add Custom APIAPI を直接入力します。3. Version ごとの API 連携と同じです。
  1. 6-1接続方式

    1. Load Model、Load Agent、Add Custom API のいずれかを選びます。

    Add Custom API は 3. Version ごとの API 連携と同じです。

  1. 6-1モデルの読み込み

    1. Model List でモデルを選びます。Deleted のモデルは選択できません。
    2. Validate & Load をクリックします。
  2. 6-2Agent の読み込み

    1. Agent List で Agent を選び、Next をクリックします。
    2. Agent Version List で Version を選び、Validate & Load をクリックします。
  3. 6-3Output Key のマッピング

    1. パスに response_1. プレフィックスを付けてマッピングし、Save をクリックします。

    Pick from response で選ぶと、プレフィックスが自動で付きます。

読み込んだモデルと Agent のレスポンスパスには response_1. プレフィックスを付けます(例:response_1.result.answer)。Pick from response で選ぶと自動で付きます。


よくある質問

Module の Key を編集すると、なぜ Version 設定が消えるのですか?Key を 1 つでも編集すると、すべての Version 設定が初期状態に戻るためです。
原因
Version 設定は Module の Key 構成を基準に作られているためです。
解決方法
Version 設定を最初からやり直してください。
Request Body の変数が実際の値に置き換わらないのはなぜですか?変数名が Input Key 名と一致していないためです。
原因
{{key_name}} の名前は Input Key と完全に一致している必要があります。
解決方法
変数名を Input Key とまったく同じ名前に修正してください。
Go to Output Mapping を押せないのはなぜですか?URL が空欄か、必須変数が使われていないか、Turn Definition に空欄があるためです。
原因
ダイアログ下部の Required variables をすべて使わないと次に進めません。
解決方法
赤いメッセージと空欄を確認してください。
Test Connection で認証エラーや形式エラーが出るのはなぜですか?Header の認証情報か Request Body の形式が間違っているためです。
原因
テストは入力した設定のまま API を呼び出します。
解決方法
Header と Request Body を修正してから、もう一度テストしてください。
Multi-turn で ...{{chat_history}} のエラーが出るのはなぜですか?Request Body に ...{{chat_history}} がないか、綴りが間違っているためです。
原因
過去の会話はこの位置に入ります。
解決方法
デフォルト例のように messages 配列の中に入れてください。
スコアが変わった原因を追跡できない場合はどうすればよいですか?Output Key のマッピングを確認してみてください。Extracted Value で値を確認してから保存してください。
原因
誤ってマッピングされた Key は、すべての評価結果を不正確にします。
解決方法
Extracted Value で値を確認してから保存してください。
コストが計算されないのはなぜですか?トークンパスが間違っているか、単価が入力されていないためです。
原因
2 つのパスと 2 つの単価がすべて揃って、はじめてコストが計算されます。
解決方法
プロバイダーごとのパスを参考に、もう一度入力してください。

最終更新日