Jev APIを使うと、アプリケーションから「候補の選択」「段階評価」「Yesの確率」を取得できます。自由文の生成ではなく、プログラムがそのまま扱いやすい構造化判断を返す点が特徴です。
API連携で最も重要なのは、正常なレスポンスを受け取ることではありません。候補外の値、低い確信度、タイムアウト、重複リクエストが起きたときに、安全側へ止まれることです。モデルが高い確率を返しても、ユーザー権限、対象リソース、金額、引数の妥当性はアプリケーション側で確認します。
最初の実装は、一つのchoiceと読み取り専用処理に限定してください。過去データで人の判断と比較し、低確信度だけを人へ回す仕組みを作ります。その後、取り消せる書き込み、重要操作の順に段階を上げると、問題の原因を追いやすくなります。
業界・職種別「生成AI活用事例集」全11種 無料ダウンロード
Jev APIは何を返す？
| 型 | 用途 | 返り値の例 |
|---|---|---|
| choice | 複数候補から選択 | 選択肢と確率 |
| score | 順序付きの評価 | リスク段階と確率 |
| noul | 二値判断 | Yesの確率 |
公式ドキュメントでは、Jevは状態と質問を受け取り、型付きの答えを返すモデルとして説明されています。チャット用の/chat/completionsへ置き換える設計ではありません。[[2]](https://docs.typesafe.ai/introduction/coding-agents)
実装前に決める4項目
- 判断対象と正解の定義
- 候補または評価基準
- 入力する状態の範囲
- 低確信度・エラー時の処理
APIを呼ぶ前に、この4点を仕様書へ記載します。曖昧な判断をそのままモデルへ渡すと、結果を評価できません。
最小実装の考え方
以下は構造を理解するための例です。実際のURL、フィールド名、認証方法は公式API仕様へ合わせてください。
const response = await fetch(process.env.JEV_API_URL, {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.JEV_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "typesafe-ai/jev",
state: "問い合わせ内容と契約状態を要約した文字列",
questions: {
route: {
type: "choice",
instructions: "担当部署を選ぶ",
criteria: ["sales", "support", "billing"]
},
human_review: {
type: "noul",
instructions: "人の確認が必要か"
}
}
})
});
if (!response.ok) throw new Error(`Jev API error: ${response.status}`);
const result = await response.json();APIキーはコードへ直書きせず、環境変数やシークレット管理へ保存します。
レスポンスを安全に扱う
返り値を受け取ったら、次の順で検証します。
- HTTPステータスと応答形式
- 期待する質問キーがあるか
- choiceが許可済み候補に含まれるか
- scoreが定義範囲内か
- 確信度が基準未満ではないか
- 人の承認が必要な処理ではないか
確率が高くても、権限や業務ルールの確認を省略しません。モデルの判断と、実行許可は分けて設計します。
エラー処理の基本
| 状況 | 処理 |
|---|---|
| 認証エラー | キーを記録せず停止し、設定を確認 |
| レート・利用上限 | 指数バックオフで再試行 |
| 形式不正 | 自動実行せず人へ回す |
| 低確信度 | 既定の安全経路へフォールバック |
| タイムアウト | 重複実行を防いで再処理 |
送金や削除など副作用のある処理では、冪等性キーと監査ログを用意します。
自社に合う研修内容を、業務内容から一緒に整理します
本番導入までの5ステップ
1. テストデータを作る
機密情報を除いた過去データを用意し、人による正解ラベルを付けます。
2. オフライン評価を行う
正解率だけでなく、誤判定の種類と確信度を確認します。
3. シャドー運用する
本番の判断には使わず、Jevの結果だけ記録して人の判断と比較します。
4. 低リスク処理に限定する
誤りがあっても戻せる処理から開始します。
5. 監視と停止条件を設定する
エラー率、低確信度率、差し戻し率、API費用を監視します。
API設計のチェックリスト
- APIキーを安全に保管した
- 入力状態を最小化した
- 個人情報と機密情報を除いた
- 候補値をアプリ側でも検証する
- 低確信度時の経路がある
- タイムアウトと再試行を実装した
- 重要処理に人の承認がある
- ログから秘密情報を除外した
本番APIで実装する防御処理
Jevのレスポンスが正常でも、アプリケーション側の検証は必要です。モデルの出力を信頼境界の外側に置き、通常のAPI入力と同じように扱います。
function validateDecision(result, allowedRoutes) {
if (!result || typeof result !== "object") {
return { ok: false, reason: "invalid_response" };
}
const route = result.route?.choice;
const confidence = result.route?.confidence;
if (!allowedRoutes.includes(route)) {
return { ok: false, reason: "unknown_route" };
}
if (typeof confidence !== "number" || confidence < 0.8) {
return { ok: false, reason: "human_review" };
}
return { ok: true, route };
}実際のレスポンス構造は公式仕様へ合わせてください。重要なのは、候補値、型、確信度、欠損をアプリ側でも検証することです。
タイムアウト・再試行・重複実行を設計する
API障害に備え、接続タイムアウトと全体タイムアウトを設定します。再試行は認証エラーや形式不正には行わず、一時的なサーバーエラーやレート制限に限定します。
| 状況 | 再試行 | 対応 |
|---|---|---|
| 400系の入力不正 | しない | 入力とスキーマを修正 |
| 401・403 | しない | キー・権限を確認 |
| 429 | 待って再試行 | Retry-Afterを尊重 |
| 500系 | 回数制限付き | 指数バックオフ |
| タイムアウト | 条件付き | 重複実行を確認 |
副作用のある処理へつなぐ場合は、リクエストIDや冪等性キーを保存します。同じ判断リクエストが再送されても、送金や通知が二重に実行されない構造にしてください。
ログへ残す項目・残さない項目
残すのは、リクエストID、モデルID、質問のバージョン、判断結果、確信度、処理時間、人の最終判断です。APIキー、パスワード、不要な個人情報、完全な機密文書は記録しません。
ログはモデル監視だけでなく、後から「なぜこの処理が選ばれたか」を確認する監査記録として使います。
よくある質問
ChatGPT APIと同じように使えますか？
用途が異なります。Jev APIは文章生成ではなく、型付き判断を返すために使います。
API結果をそのまま実行してよいですか？
不可逆な処理ではそのまま実行せず、権限、対象、金額、業務ルール、人の承認を確認します。
どの指標を監視すべきですか？
エラー率、低確信度率、人との不一致率、差し戻し率、応答時間、費用を確認します。
MoMoなら運用から逆算したAI API導入を実現できます
API連携では、呼び出しコードよりも、誤判定時の停止、承認、監査、再処理の設計が成果を左右します。株式会社MoMoでは、業務選定、検証データ、評価指標、運用ルールをまとめて設計します。
1. 向いている企業・向いていない企業
反復する判断を標準化し、APIログを運用できる企業に向いています。正解基準や責任者が不明な状態では、先に業務フローを整理します。
2. 活用例
検証用の架空問い合わせを使い、ルーティング結果、人の正解、確信度を比較します。低確信度だけ担当者へ回す経路まで確認します。
業界・職種別の活用事例11種を無料で配布しています
Jev APIの使い方まとめ：最小実装から安全な判断APIを検証しよう
Jev APIは、状態と型付き質問を送って構造化判断を得るAPIです。候補値の検証、低確信度時のフォールバック、承認、ログをアプリ側で実装してください。
まずは一つのchoiceを実装し、許可済み候補、低確信度、タイムアウトの3ケースを過去データと人の判断でテストしてください。
他のAPI・AI活用例を比較したい方は、「生成AI活用事例50選」を参考にできます。本番の権限・監査・再処理まで設計する段階では、個別相談を活用してください。
研修内容・費用のご相談は無料です
