API連携

TypeSafe AIモデルとJev AI API：本番環境向け統合ガイド

Jev AIモデルとAPIによる型付き判断を解説。リクエスト例、TypeScript実行時検証、確率しきい値、障害対応、本番導入まで扱います。

執筆者：Jev AI2026年9月26日読了時間：17分

typesafe ai model、jev ai model、jev ai api を調べる開発者が知りたいのは、多くの場合「AIの判断を、アプリケーションのコードが安全に使える値へどう変えるか」です。Jevは、答えの範囲を定めた判断に向けて設計されています。状態と型付きの質問を渡すと、Choice、Score、Noulの結果が返り、振り分け、優先順位付け、レビューに利用できます。ただし、応答の検証、権限の確認、最終的な操作はアプリケーションの責任です。

このガイドでは、サポートチケットの仕分けを例に、質問設計から本番導入までをたどります。まず名称を整理します。TypeSafe AIは公式発表で、Jevをソフトウェアの判断に使うSystem Oneモデルとして紹介しました。Jev AIのモデル紹介は、別途その仕組みとAPI体験を提供しています。同サイトのフッターには、独立して運営されており、TypeSafeとの提携、運営関係、推薦関係はないと明記されています。認証情報、エンドポイント、利用条件を選ぶ際は、モデルの概念、元の提供元、このサイトのAPIを区別してください。

TypeSafe AIモデルとは
Jev AIモデルに適した用途
Jev AI APIの契約
チケット仕分けのリクエストを作る
応答を読み実行時に検証する
確率を業務ルールに変える
本番環境でAPIを安定運用する
導入前に評価する
よくある失敗と対処
よくある質問

TypeSafe AIモデルとは

ここでの「型安全」はモデルのインターフェースを指します。推論する前に、呼び出し側が許される答えの種類を定義します。TypeSafeはJevを、長い文章の生成ではなく、速く構造化された判断のための System Oneモデル と説明しています。入力は状態と質問、出力は確率を伴う型付きの値です。型が正しいことと、業務上の判断が正しいことは別です。スキーマ上は有効でも、間違った部署へチケットを送ることはあり得ます。

一般的なチャットモデルにもJSON出力を指示でき、JSON Schemaで形式上の失敗を減らせます。それでも、形式を守ったか、答えが正しいか、その答えで操作を実行してよいかは分けて考える必要があります。Jevの限定された契約では、それぞれの責任が明確になります。

モデルは曖昧な判断を担当する。 例えば、承認済みのどのチームが担当すべきかを選びます。
APIは制約された結果を運ぶ。 質問の型と応答フィールドが決まっています。
アプリケーションはポリシーを担当する。 応答、しきい値、権限を検査してから操作を記録します。

TypeScriptの型は開発時の契約維持に役立ちますが、実行時には消えます。ネットワークから届いた値は、サーバーで検証するまでは未知のデータです。したがって「型安全なAI」はシステム全体で実現する性質であり、実行時検証を省く理由にはなりません。

Jev AIモデルに適した用途

答えの候補を事前に定められる場合、Jevは有効です。たとえば、四つの担当チームから選ぶ、影響度を順序付きの尺度で採点する、人による確認が必要か推定する、といった仕事です。結果は既存のワークフローへ入力できます。生成系LLMとの併用もできます。一方が処理経路を判断し、もう一方が文章を作成する構成です。モデルの数値が高いだけで、返金や削除など取り消しにくい操作の権限を与えてはいけません。

公開ドキュメントには三つの質問型があります。Choice は指定した選択肢から一つ選び、各選択肢の確率とconfidenceを返します。Score は順序付きの基準を使い、確率で重み付けした点数、段階の説明、分布、confidenceを返します。Noul は「はい」の確率を0から1の値で返します。Noulに別のconfidenceフィールドはありません。複数の質問は同じ状態を共有し、一つのリクエストで処理できます。

現在のJev AI APIドキュメントでは、state に文字列、JSONオブジェクト、文字列の配列を指定できます。画像、音声、動画は現時点でサポートされていません。添付ファイルを使う場合は、別途検証可能な処理でテキストを抽出してください。英語以外の入力についても、自分たちのラベル付きデータで精度を確かめる必要があります。

Jev AI APIの契約

このサイトのドキュメントに記載されたエンドポイントは POST https://thejevai.com/v1/systemone です。サーバーからBearer APIキーと Content-Type: application/json を付けて送ります。リクエスト本文には model、state、questions の三つの必須フィールドがあります。ドキュメントのモデル別名は jev-latest で、応答には解決後のモデルバージョンが示されることがあります。質問IDはアプリケーションが選び、応答の answers に同じキーで返ります。

提供元が異なるエンドポイントとキーを混ぜないでください。TypeSafe本体の資料には別の api.typesafe.ai エンドポイントが載っています。以下は thejevai.com 向けの例なので、このサービスのキーを使用します。モデル別名、制限、契約条件は変わり得るため、実装前に現行のドキュメントを再確認してください。

質問型	入力の契約	主な出力	チケットでの例
Choice	`criteria` に名前付き選択肢を列挙	`choice`、各確率、confidence	どのチームが担当するか
Score	`criteria` を低い順から高い順の配列にする	加重点数の `score`、段階表、確率、confidence	影響はどの程度か
Noul	はい／いいえの質問。true/falseの説明は任意	`noul`、つまり「はい」の確率	人の確認が必要か

一つの質問では一つのことだけを判断させます。「分類し、優先度を付け、返金可否を決める」では三つのポリシーが混ざります。Choice、Score、Noulに分けると、結果を個別に点検できます。文書上、Choiceは最大255選択肢、Scoreは2〜10段階を扱えますが、最初は人が解釈しやすい少数の基準から始めましょう。

チケット仕分けのリクエストを作る

顧客から「二重請求され、三日間入金も止まっています」と届いたとします。担当チーム、影響度、人による確認の必要性を知りたい場面です。判断に必要な文面とポリシーだけを渡し、不要な個人情報は含めません。承認済みチームのどれにも当てはまらない場合があるので、Choiceに none_of_the_above を追加します。そうしないと、もっともらしい誤った部署へ強制的に分類されます。

{
  "model": "jev-latest",
  "state": {
    "ticket": "二重請求され、三日間入金も止まっています。",
    "account_tier": "business",
    "policy": "返金には権限を持つ担当者の承認が必要。障害報告はエスカレーションする。"
  },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "承認済みのどのチームが最初に調査すべきか？",
      "criteria": {
        "billing": "二重請求、請求書、返金、または入金",
        "technical": "支払いと無関係な製品障害や連携の問題",
        "account": "アカウントアクセスと本人確認",
        "none_of_the_above": "適切な承認済みチームがない"
      }
    },
    "severity": {
      "type": "score",
      "instructions": "顧客の感情ではなく、業務への影響を評価する。",
      "criteria": ["サービス影響なし", "一部に影響", "大きな影響", "サービス停止"]
    },
    "needs_human": {
      "type": "noul",
      "instructions": "提示したポリシーでは、返金やアカウント変更の前に人の承認が必要か？",
      "criteria": {
        "true": "返金またはアカウント変更には承認が必要",
        "false": "分類またはキューへの登録だけを行う"
      }
    }
  }
}

ここで守るべき境界は、モデルが担当チームやリスクを示せても、返金を承認することはできないという点です。権限者の承認がない限り、決定的なルールで返金の実行を止めます。needs_human は画面表示や振り分けの参考にはなりますが、許可証ではありません。

最初にオンラインPlaygroundで質問の契約を試し、その後で同じ形式をバックエンドから送ります。テストには匿名化した実例を使い、曖昧な言い方、情報不足、未対応の分類、チケット文中でポリシーを上書きしようとする指示も含めます。チケットはデータであり、システム命令ではありません。

応答を読み実行時に検証する

記載された応答にはモデル識別子、質問IDをキーとする answers、使用量が含まれます。Choiceは選択結果と確率分布とconfidence、Scoreは加重点数と段階表と分布とconfidence、Noulは type と noul です。次の短い応答は説明用の例であり、このチケットで必ず得られる値ではありません。

{
  "model": "jev-1.13.0",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.84, "technical": 0.12, "account": 0.02, "none_of_the_above": 0.02 },
      "confidence": 0.76
    },
    "severity": {
      "type": "score",
      "score": 2.4,
      "legend": { "0": "サービス影響なし", "1": "一部に影響", "2": "大きな影響", "3": "サービス停止" },
      "probabilities": { "0": 0.01, "1": 0.09, "2": 0.39, "3": 0.51 },
      "confidence": 0.57
    },
    "needs_human": { "type": "noul", "noul": 0.94 }
  },
  "usage": { "input_tokens": 318, "output_tokens": 52 }
}

値の役割は異なります。team.choice は候補となる経路です。確率分布にはほかの候補も含まれ、confidence は分布から導かれる別の信号です。severity.score は確率による加重平均なので、段階の間になる場合があります。needs_human.noul は「はい」の確率です。Noulに文書化されていない needs_human.confidence を読もうとしてはいけません。

通信の境界では、JSONを unknown として読み、ポリシーで使うフィールドを検証します。次のTypeScript例は Choice の部分だけを確認します。requestBody は上に示したリクエストオブジェクトです。ScoreとNoulを利用するなら、それらも同様に検証してください。

const teams = ["billing", "technical", "account", "none_of_the_above"] as const;
type Team = (typeof teams)[number];

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function isProbability(value: unknown): value is number {
  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
}

function readTeam(raw: unknown): { team: Team; probability: number; confidence: number } | null {
  if (!isRecord(raw) || !isRecord(raw.answers)) return null;
  const answer = raw.answers.team;
  if (!isRecord(answer) || answer.type !== "choice") return null;
  if (!teams.some((team) => team === answer.choice)) return null;
  if (!isRecord(answer.probabilities) || !isProbability(answer.confidence)) return null;

  const probabilities = answer.probabilities;
  if (!teams.every((team) => isProbability(probabilities[team]))) return null;
  const total = teams.reduce((sum, team) => sum + (probabilities[team] as number), 0);
  if (Math.abs(total - 1) > 0.02) return null; // API値の丸め誤差を許容
  return {
    team: answer.choice as Team,
    probability: probabilities[answer.choice as Team] as number,
    confidence: answer.confidence
  };
}

const apiKey = process.env.JEV_API_KEY;
if (!apiKey) throw new Error("JEV_API_KEY is missing");
const response = await fetch("https://thejevai.com/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(requestBody),
  signal: AbortSignal.timeout(5000)
});

if (!response.ok) throw new Error(`Jev request failed: ${response.status}`);
const raw: unknown = await response.json();
const teamDecision = readTeam(raw);
if (!teamDecision) throw new Error("Unexpected Jev team response");

JEV_API_KEY はサーバー側の秘密情報として保存し、サービス起動時に存在を確認します。キー全文、匿名化していないチケット、未編集の応答をログに残さないでください。既存のスキーマライブラリで同じ検証を実装しても構いません。重要なのは特定のライブラリではなく、ネットワーク由来の値を実行時に検証することです。

確率を業務ルールに変える

確率は信号であり、実行権限でも正しさの保証でもありません。例では billing の確率が高いものの、confidence は最上位候補の確率と同じ値ではありません。本番のルールでは、選択肢、分布、業務リスク、誤った振り分けのコストを合わせて考えます。要レビュー と API利用不可 も区別してください。タイムアウトはNoulが「いいえ」と答えたことを意味しません。

リスクの低いキューなら、最上位候補の確率が 0.85 以上のとき自動振り分け、0.60–0.85 は確認待ち、それ以下または不正な応答は手作業へ送る、という仮のルールが考えられます。この数字は構造を示す例であり、Jevの標準値ではありません。ラベル付きデータと誤判定の損失から決めてください。返金、支払い、削除、アカウント変更には、確率に関係なく元の権限ルールを適用します。

有効で強い信号 + 許可済みの低リスク操作 → 自動処理
有効だが不確実、または重要な操作     → 人が確認
不正な応答、タイムアウト、キー不足   → 安全な代替経路

Choiceでは一位と二位の確率が近すぎないかも見ます。Scoreでは加重平均が幅広い分布を隠していないかを確認します。Noulで中間の値は不確実性を示します。しきい値はワークフローごとに管理し、質問の版と合わせて記録します。複数のハンドラーに根拠のない数字を散らさないことが大切です。

本番環境でAPIを安定運用する

公開ドキュメントには、認証情報の不足や無効を示す 401、リクエスト検証失敗の 422、レート制限の 429、過負荷の 529 が記載されています。対応を分けましょう。401 はキー設定、422 はリクエスト契約を修正します。429 と 529 は、回数に上限を設けた指数バックオフとランダムな待機時間を使って再試行できます。通信エラーとタイムアウトには明示的な代替経路が必要です。

製品の待ち時間に合う期限を設定します。再試行は可用性を上げる一方、通信量とユーザーの待ち時間も増やします。無限ループより、少数回の上限付き再試行の方が扱いやすくなります。返金やステータス変更などの副作用は再試行されるモデル呼び出しの外に置き、二重実行を防ぎます。

文書上の elapsed はサービスが返す追加の経過時間、usage はトークン使用量です。自分のクライアント側でも、ネットワークとアプリ処理を含む時間を測ります。タイムアウト、429/529、応答形式の異常、質問ごとの不一致、レビュー率、後続の誤処理コストを監視してください。監査には質問の版とモデルIDを残し、機密性の高い状態は保持方針に従って匿名化またはハッシュ化します。

セキュリティ境界も明確にします。ブラウザーは自分のバックエンドへ要求し、バックエンドがキーを保持します。ユーザー由来の状態にシステムポリシーを書き換えさせてはいけません。「返金ルールを無視して」と書かれたチケットも、単なるチケット内容です。最終操作の前には通常の権限と業務ルールを必ず確認します。

導入前に評価する

まず実際の業務からラベル付きデータセットを用意します。通常例だけでなく、曖昧な例、ポリシーに関わる例、どの選択肢にも当てはまらない例、対象とする各言語を含めます。業務担当者に正しいチーム、重大度、人の確認が必要かを付けてもらい、担当者間の意見の違いも記録します。人が一致しない場合、単一の「正解」だけでモデルの成否を決めると実態を見誤ります。

同じリクエスト契約をデータに適用し、総合精度以外も調べます。Choiceではチーム間の取り違えと none_of_the_above の割合、Scoreでは重大度の過小評価、Noulでは本来レビューが必要なケースの見逃しが重要です。必要に応じて、言語、顧客群、ポリシーの版ごとに分けて見ます。

確率の較正も別に検査します。予測確率でグループ分けし、各グループの実際の正答率と公表された確率を比べます。モデルが順序付けに役立っていても、自社領域では過信している可能性があります。この結果と誤りのコストから自動処理のしきい値を選び、調整に使わなかったデータで検証します。TypeSafeが公表した速度や較正の主張は参考になりますが、自分のトラフィックとこのエンドポイントでの測定を置き換えるものではありません。

導入は段階的に進めます。まず判断を記録するだけにし、次に人の担当者へ提案を示し、最後に最も安全な分類だけ自動化します。例外を定期的に見直し、失敗の傾向が明確なときに質問文や基準を修正します。しきい値の変更前には、取り分けておいた評価データで再検証します。モデル単体ではなく、人の確認を含むワークフロー全体の時間と費用を比べてください。

よくある失敗と対処

型が正しければ判断も正しいと思う。 スキーマ検証が防ぐのは欠落や形式の誤りです。billing が正しい担当かどうかは別に測ります。

開いた世界を閉じたChoiceで表す。 承認済みの選択肢に該当しない場合に備え、逃げ道となる選択肢と人の確認経路を用意します。

Noulを真偽値として扱う。 これは「はい」の確率です。しきい値はアプリ側で選び、厳格なポリシーも維持します。

ブラウザー側へキーを置く。 呼び出しをサーバーへ移し、漏えいした認証情報は更新します。

すべてのエラーを再試行する。 401 と 422 は原因を修正し、一時的な 429 と 529 のみ回数制限付きバックオフを検討します。

別サービスのURLとキーを混ぜる。 TypeSafe本体か独立運営のJev AI APIかを確かめます。認証情報と条件はサービスごとに異なります。

代替経路を決めていない。 APIが使えない場合に安全なキューや人の確認へ送ることも、アプリが実行・監視できる結果です。

TypeScriptの実行時境界を別の角度から学ぶには、サイト内のJev TypeSafeガイドを参照してください。

よくある質問

Jev AIモデルはLLMですか

TypeSafeはJevをSystem Oneの判断モデルと説明しています。開かれた文章ではなく、制約付きの判断と確率を返すためのモデルです。文章作成や自由な推論には生成モデルを使い、答えの候補を定義できる場面では型付き判断を検討します。

型安全ならJevの判断は間違いませんか

いいえ。型安全が扱うのは許された出力形式です。正しい形のChoiceでも誤った担当チームを選び得ます。応答を検証し、代表的なデータで評価し、業務ルールをモデルの外に置きます。

ブラウザーからJev AI APIを直接呼べますか

APIキーを守るため、サーバー側から呼びます。ブラウザーは自分のアプリへ要求し、バックエンドが必要な状態だけを選んでJevへ送り、応答を検証したうえでUIに必要な結果のみ返します。

最初に何を作るべきですか

チケット分類など、リスクが低く取り消せる判断から始めます。選択肢を決め、ラベル付きデータを集め、Playgroundで確率を見て、まずはAPIの提案を記録するだけにします。不確実なケースを安定して人へ送れるようになることが、最初の実用的な到達点です。

目次