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 Key | Module に渡される入力 |
Output Key | Module の実行後に生成される出力 |
①1-1. Module の作成
-
+ New Moduleをクリックします。 -
Module Type を選択します。複数の Module Type を選択できます。
-
Addをクリックします。
②1-2. Module の編集
-
Module 右上の編集(鉛筆)アイコンをクリックします。
-
Module 名、Input Key、Output Key を編集します。
-
必要に応じて Key を追加します。
| ボタン | 動作 |
|---|---|
+Add Input Key | Input Key を追加します。 |
+Add Output Key | Output Key を追加します。 |
Input Key または Output Key を 1 つでも編集すると、この Application のすべての Version 設定を最初からやり直す必要があります。
③1-3. Module の削除
-
Deleteボタンをクリックします。 -
入力欄に
Delete moduleと入力します。Deleteボタンが有効になります。 -
Deleteをクリックします。Module が削除されます。
1-1Module の確認
- Agent Connection の
Module Listで Module と Key を確認します。
- Agent Connection の
1-2Module の追加・編集
+ New Moduleで追加します。- Module カードの編集ボタンで名前と Key を変更します。
Saveをクリックします。
Key を 1 つでも編集すると、この Module のすべての Version 設定をやり直す必要があります。
1-3Module の削除
- 編集ダイアログの
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. 連携情報の入力
- Version の行で
API Integrationをクリックします。 - 以下の情報を入力します。
| 項目 | 入力内容 |
|---|---|
API URL | 呼び出す API の URL |
Method | リクエスト方式。通常はデフォルトの POST のまま使います。 |
Request Header | 認証キーなどのヘッダー。Content-Type: application/json はあらかじめ入力されています。 |
Request Parameter | URL の後ろに付ける値。必要な場合のみ入力します。 |
Request Body | 送信する内容(JSON)。3-2 で説明します。 |
Authorization、x-api-key などの API キーは、保存すると sk-****6789 のようにマスクされます。評価時には元の値が使われます。キーを変更するには、マスクされた欄をクリックして新しい値を入力します。
②3-2. Request Body の作成
- リクエスト本文を JSON で作成します。
- ステップ 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. 接続テスト
- 右側の
Test Connectionに、変数ごとにサンプル値を入力します。 Test Connectionをクリックします。- レスポンスが正しく返ってくるか確認します。
認証エラーや形式エラーをここで事前に見つけておけば、評価中に大量に失敗するのを防げます。
④3-4. 保存
| ボタン | 使うタイミング |
|---|---|
Save Draft | まだ入力が終わっていないときに、ここまでの入力内容を一時保存します。 |
Go to Output Mapping | 入力が終わったら、次のステップ(5. Output Key のマッピング)に進みます。 |
保存せずにダイアログを閉じると、保存するかどうかを確認するダイアログが表示されます。
3-1連携ダイアログを開く
- Version 行の赤い
API Integrationをクリックすると、Set up Versionダイアログが開きます。 Version Nameを確認します。
- Version 行の赤い
3-2URL と Method
URLに呼び出す API の URL を入力します。Methodを選びます。通常はPOSTです。
URL が空欄、または形式が正しくない場合は赤いメッセージが表示されます。
3-3Request の設定
- 案内ボックスで、この Application の入力変数を確認します。
- 必要に応じて
Request Headerに認証キーを入力します。 Request Bodyに変数を{{key_name}}の形式で挿入します。
ダイアログ下部の
Required variablesをすべて 1 回以上使う必要があります。3-4接続テスト
- 右側の
Test Connectionに、変数ごとにサンプル値を入力します。 Test Connectionをクリックし、レスポンスを確認します。
- 右側の
3-5保存
- まだ入力が終わっていなければ
Save Draftをクリックします。 - 入力が終わったら
Go to Output Mappingをクリックします。
- まだ入力が終わっていなければ
4. マルチターン API 連携
チャットボットのように過去の会話もあわせて送る必要がある API は、Multi-turn をオンにして連携します。質問を 1 つだけ送る API であれば、このステップは飛ばしてください。
①4-1. Multi-turn をオンにする
- API 連携ダイアログ左側の
Multi-turnトグルをオンにします。 - 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) |
{{content}}行のUser Turnで入力変数(例:{{query}})を選びます。- 同じ行の
Assistant Turnに、エージェントの回答があるパスを入力します。パスがわからない場合はPick from responseを押し、レスポンスから回答を選んでSelectをクリックします。 - フィールドがさらに必要な場合は
+ Add Variableで追加します。Request Body にも自動で挿入されます。
空欄が 1 つでもあると、次のステップに進めません。
③4-3. 2 ターンの接続テスト
Multi-turn の Test Connection には Turn 1、Turn 2 の欄があります。
Turn 1に最初の質問、Turn 2に続きの質問を入力します。
(例:私の名前はダトゥモです。→私の名前は何でしたか?)Test Connectionをクリックします。- Turn 2 のレスポンスが Turn 1 の内容を覚えているか確認します。
2 つのターンがどちらも成功して、はじめてテスト完了とみなされます。失敗したターンは、結果にマウスを合わせて再試行アイコンから再実行します。
4-1Multi-turn をオンにする
Multi-turnトグルをオンにします。Request Body に...{{chat_history}}のデフォルト例が入力されます。Turn Definitionで、過去の会話の 1 ターンを埋める値を決めます。
Multi-turn では API Chaining を使用できません。
5. Output Key のマッピング
API レスポンスのどの値を評価するかを指定するステップです。Go to Output Mapping を押すとダイアログが開きます。
①5-1. レスポンスパスの入力
- Output Key ごとに、レスポンス内のパスを入力します。パスがわからない場合は
Pick from responseでレスポンスから値を選んで入力します。
| Output Key | パスの例 |
|---|---|
answer | response_1.choices[0].message.content |
retrieved_docs | response_1.context.documents |
- パスの下の
Extracted Valueに表示された値が正しいか確認します。 Saveをクリックします。
- パスが間違っていると赤いメッセージが表示され、保存できません。
- 接続テストを行っていない場合は、保存時にテストするかどうかを確認されます。
誤ってマッピングされた Key は、すべての評価結果を不正確にします。スコアが変わった理由を追跡できなくなります。
②5-2. トークン使用量とコスト(任意)
コストを確認したい場合のみ設定します。設定すると、Run Report の Usage タブとエージェントシミュレーションでコストが表示されます。
- 同じダイアログ下部の
Token Usage & Costで、Input Tokens、Output Tokensのパスを入力します。Pick from responseで選んでもかまいません。 Input token cost ($)、Output token cost ($)に 100 万トークンあたりの価格を入力します。- 下のボックスに推定コストが表示されたら、
Saveをクリックします。
よく使われるトークンパスは以下のとおりです。
| プロバイダー | 入力トークン | 出力トークン |
|---|---|---|
| OpenAI、vLLM、Ollama(OpenAI 互換) | usage.prompt_tokens | usage.completion_tokens |
| Anthropic、OpenAI Responses | usage.input_tokens | usage.output_tokens |
| Gemini | usageMetadata.promptTokenCount | usageMetadata.candidatesTokenCount |
- 後で設定するには Version 行の
Go to Settingを、修正するにはEdit Tokenを押します。 - すでに実行した評価のコストは、Run Report で設定すると再計算されます。評価レポートを参照してください。
5-1レスポンスパスの入力
- 左側で
Test Connectionを実行し、レスポンスを取得します。 - Output Key ごとに
Pick from responseをクリックします。 - レスポンスから値を見つけて
Selectをクリックします。 Extracted Valueで値を確認します。
パスが間違っていると赤いメッセージが表示され、保存できません。
- 左側で
5-2トークン使用量とコスト(任意)
Input Tokens、Output Tokensのパスを入力します。- 100 万トークンあたりの単価を入力し、推定コストを確認します。
5-3保存
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 API | API を直接入力します。3. Version ごとの API 連携と同じです。 |
6-1接続方式
Load Model、Load Agent、Add Custom APIのいずれかを選びます。
Add Custom APIは 3. Version ごとの API 連携と同じです。
6-1モデルの読み込み
Model Listでモデルを選びます。Deletedのモデルは選択できません。Validate & Loadをクリックします。
6-2Agent の読み込み
Agent Listで Agent を選び、Nextをクリックします。Agent Version Listで Version を選び、Validate & Loadをクリックします。
6-3Output Key のマッピング
- パスに
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 つの単価がすべて揃って、はじめてコストが計算されます。
- 解決方法
- プロバイダーごとのパスを参考に、もう一度入力してください。