Jev AI APIチュートリアル：Choice・Score・Noulで初めての構造化された判断を作る

Jev AI Playgroundでモデルを試したことがあるなら、次は実際の判断をサーバー側のワークフローにつなぐのが一般的です。チケットやメッセージを受け取り、製品で必要な質問を定義し、確率と信頼度を読み取り、振り分け、キューへの登録、人による確認のいずれにするかをコードで決めます。

Jev AI APIは、主にチャットリクエストを行うためのものではありません。中心となるモデルは、State、Model、Questionsという3つの明確な入力です。Stateがコンテキストを表し、Questionsが判断内容を表し、レスポンスは質問IDごとに型付きの結果を返します。これにより、新たなチャット画面を追加するのではなく、既存の関数、キュー、エージェントワークフローにAIの判断を組み込めます。

この記事では、リクエスト形式、Choice・Score・Noulの使い分け、最小限のcurlリクエスト、レスポンス処理、制御フロー、エラー境界、本番環境向けチェックリストを説明します。

チュートリアルの目標： リスクの低いサポートチケットの判断を作り、サーバーが自動で振り分けるか、人による確認を依頼するかを決められるようにします。

目次

• Jevのリクエストモデルを理解する
• State：コンテキストを渡す
• Questions：Choice、Score、Noulを選ぶ
• 初めてのJev APIリクエストを送る
• レスポンスを読み取り処理する
• 結果をアプリケーションロジックにつなぐ
• 本番環境向けチェックリスト
• よくある質問

Jevのリクエストモデルを理解する

画像：Stateがコンテキストを提供し、Questionsが判断内容を記述し、構造化された結果がサービスに返されます。

基本的な考え方は次のとおりです。

state + model + questions
            ↓
typed answers + probabilities + confidence
            ↓
your application logic

現在のWebサイトのドキュメントでは、本番リクエストのエンドポイントとして POST https://thejevai.com/v1/systemone が案内されています。リクエストには、次の3つの主要フィールドがあります。

• state：文字列、JSONオブジェクト、またはテキストの配列。
• model：typesafe/jev-1.13などのモデル名。
• questions：業務上安定したIDをキーにした型付きの質問。

判断を行うのはJevです。一方、認証、入力のサニタイズ、しきい値、再試行、ログ記録、最終的なアクションは引き続きアプリケーション側の責任です。製品全体の考え方についてはJev AIの紹介をご覧ください。

State：コンテキストを渡す

単純なケースでは文字列を使う

判断対象が1つのメッセージだけなら、文字列が最も簡単なStateです。

{
  "state": "The customer has tried to connect Stripe for three days."
}

サポートメッセージ、アラート、フォームの説明、ユーザーフィードバック、短いチケットに適しています。

構造化されたコンテキストにはJSONオブジェクトを使う

チケット、注文、ポリシーを同時に判断に使う場合は、オブジェクトを使います。

{
  "ticket": {
    "text": "The customer has tried to connect Stripe for three days.",
    "channel": "email"
  },
  "customer": {
    "plan": "pro",
    "days_open": 3
  },
  "policy": {
    "same_day_escalation": true
  }
}

オブジェクトを使うと、すべての質問で共通の事実を参照できます。ただし、システムの全フィールドを送るべきという意味ではありません。判断に必要な最小限のコンテキストだけを渡し、秘密情報、決済データ、不要な個人情報はサービスの外にリクエストを送る前に取り除いてください。

関連するテキストには配列を使う

複数のメッセージ、検索で取得した抜粋、会話の要約は、テキストの配列として表せます。各項目は現在の判断に関係するものにしてください。無関係な情報をStateに混ぜても、モデルが完璧に無視するとは限りません。

現在のサイトドキュメントでは、テキスト、JSONオブジェクト、テキスト配列がサポート対象として記載されています。画像、音声、動画は現時点で直接入力できません。事前に文字起こし、OCR、または別のサービスで処理してください。

Questions：Choice、Score、Noulを選ぶ

画像：質問タイプによってレスポンスの形式と、結果が制御フローに入る方法が決まります。

質問タイプ	用途	主な結果	典型的なアクション
Choice	選択肢から1つ選ぶ	choice、probabilities、confidence	振り分け、分類、モデル選択
Score	順序のある基準で評価する	score、legend、probabilities、confidence	ランキング、優先度、SLA
Noul	記述が真かどうかを判断する	noul（はいの確率）	ブロック、確認、エスカレーション

Choice：分類と振り分け

回答候補を列挙できる場合にChoiceを使います。サポートチーム、コンテンツカテゴリ、タスクの種類、モデルのプランなどが該当します。誤った一致を無理に選ばせず、不明なケースに備えて other や none-of-the-above を追加してください。

Score：順序のある評価

深刻度、満足度、緊急度、リスクレベルにはScoreを使います。各レベルは低い方から高い方へ並べ、具体的に説明してください。「低・中・高」だけにせず、各レベルでどの業務アクションを起こすかを定義します。

Noul：1つのYes/No判断

質問を「この記述は正しいですか？」と言い換えられる場合はNoulを使います。例：「顧客は明示的に返金を求めていますか？」「このツール呼び出しには人の確認が必要ですか？」Noulは「はい」である確率を返します。独立した信頼度フィールドと混同しないでください。

TypeSafeのドキュメントでは、質問を1つの判断に分けることが重視されています。部署、優先度、リスクを1つの質問で決めるのではなく、質問を分けて結果をコードで組み合わせます。

初めてのJev APIリクエストを送る

画像：質問を増やす前に、小さく範囲を絞ったリクエストを1つ検証します。

APIキーを準備する

APIキーはサーバー側の環境変数に保存します。

export JEV_API_KEY="your-server-side-key"

実際のキーをブラウザーコード、クライアントバンドル、公開記事、Gitリポジトリに含めないでください。キー管理の最新情報はJev AI APIドキュメントを参照してください。

最小限のNoulリクエストを送る

次のリクエストは、現在の公式Webドキュメントに記載されたフィールド形式に沿っています。

curl -X POST https://thejevai.com/v1/systemone \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "A customer has tried to connect Stripe for three days.",
    "questions": {
      "urgent": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }'

Playgroundでリクエストを確認する

ChoiceまたはScoreの完全なJSON形式がわからない場合は、Playgroundで質問を定義して実行し、ページに表示されるAPIリクエストのプレビューを確認します。古い例からフィールド名を推測するより安全です。

レスポンスを読み取り処理する

画像：自動処理や確認に回す前に、レスポンスとしきい値を検証します。

質問IDで回答を読み取る

レスポンスには、送信した質問IDが使われます。概念的には次のような形式です。

{
  "answers": {
    "urgent": {
      "noul": 0.87
    }
  },
  "usage": {
    "input_tokens": 42,
    "output_tokens": 0
  },
  "elapsedMs": 214
}

これはレスポンスの例であり、完全なAPIスキーマではありません。現在のフィールド、エラー、モデルバージョンについては公式APIリファレンスを参照してください。

確率は結論ではなくシグナルとして扱う

リスクに応じて異なるしきい値を設定します。

• 低リスクのチケット振り分け：urgent > 0.8 なら自動キューに入れる場合があります。
• 中リスクのアクション：0.6–0.8 ならサンプリング確認や2回目の判断につなげる場合があります。
• 高リスクのアクション：確率が高くても、認可、固定ルール、人による確認を必ず通します。

しきい値はJevの既定値ではなく、業務ポリシーです。過去のデータや反例を使って調整してください。

エラーとタイムアウトに対応する

本番用クライアントでは、2xx以外のレスポンス、タイムアウト、フィールド不足、未知の選択肢、モデルバージョンの変更、二重送信に対応する必要があります。再試行には冪等性の仕組みが必要です。ネットワーク障害によって決済、削除、権限変更を重複実行してはいけません。

結果をアプリケーションロジックにつなぐ

例：サポートチケットの優先度フロー

result = jev.system_one(
    model="typesafe/jev-1.13",
    state=ticket,
    questions={
        "needs_human": {
            "type": "noul",
            "instructions": "Does this ticket require a human review?"
        }
    },
)

if result.answers["needs_human"].noul >= 0.85:
    queue_for_review(ticket)
else:
    route_automatically(ticket)

この例は制御フローを示しています。Python SDK、JavaScript SDK、RESTの正確なフィールドについては、最新の公式ドキュメントとPlaygroundからエクスポートしたリクエストを使用してください。

複数質問のリクエストを意図的に設計する

1つのStateに対し、複数の質問を設定できます。

• department：担当チームを選ぶChoice。
• urgency：優先度を付けるScore。
• needs_human：確認の要否を判断するNoul。

それぞれの質問では、1つの判断だけを尋ねてください。結果はアプリケーション側でアクションにまとめるため、振り分けポリシーを変更しても、緊急度や人による確認の質問を書き直さずに済みます。

本番環境向けチェックリスト

リリース前に次の項目を確認してください。

1. APIキーはサーバー側のシークレットまたは環境管理ツールにのみ保存されている。
2. Stateに長さ制限、機密データの取り扱い、権限チェックがある。
3. 各質問に安定したID、明確な回答範囲、わかりやすい指示がある。
4. クライアントがHTTPステータスとレスポンス形式を検証する。
5. 確率のしきい値は単一の共通値ではなく、リスクごとに設定されている。
6. 影響の大きいアクションに固定ルール、認可、人による確認が残っている。
7. システムがモデルバージョン、質問定義、入力の概要、最終アクションを記録する。
8. タイムアウト、再試行、フォールバック、人への引き継ぎ経路が明確である。
9. 中国語、英語、専門用語、境界ケースが評価データに含まれている。
10. 利用量やプランの詳細をJev AI料金ページと最新のAPIドキュメントで確認している。

アーキテクチャやモデル選択については、Jev AIとLLMの比較をご覧ください。エージェントの振り分けと安全対策については、Jev AIエージェントのガードレールをご覧ください。

よくある質問

Jev AI APIはチャットエンドポイントですか？

いいえ。Stateと型付きの質問を受け取り、アプリケーションが読み取れる構造化された回答を返します。チャットシステムやエージェント内の判断ノードとして使えますが、チャット形式の段落を生成するための設計ではありません。

1つのリクエストに複数の質問を含められますか？

はい。WebサイトとTypeSafeのドキュメントでは、同じStateに対して複数の質問を評価できると説明されています。各質問を独立させ、範囲を明確にし、安定したIDを割り当ててください。

Noulの値は信頼度と同じですか？

いいえ。Noulは答えが「はい」である確率です。ChoiceとScoreには、それぞれ独自の確率フィールドと信頼度フィールドがあります。正確なレスポンス形式には、常に最新のAPIドキュメントを使ってください。

Jevは画像に対応していますか？

現在のサイトドキュメントでは、テキスト、JSONオブジェクト、テキスト配列がStateの入力として記載されています。画像、音声、動画は現時点では直接入力できません。先にOCR、文字起こし、または別のモデルで処理してください。

APIが自分の製品に合うか、どう判断できますか？

回答範囲が明確で、測定可能な低リスクの判断を1つ選びます。Playgroundで検証してから、過去のデータやエッジケースを使ってサーバー側の動作をテストしてください。

まとめ

Jev AIを統合する際に重要なのは、モデルを1回呼び出すことではありません。State、質問、結果、アクションを分離することです。Stateが事実を伝え、Choice／Score／Noulが判断を行い、確率が不確実性を示し、最終的な動作はアプリケーションコードが決めます。

この流れを文書化し、テストし、監視すれば、Jev AIをPlaygroundのデモから、製品内で保守できる判断コンポーネントへ発展させられます。

調査日： 2026-09-20

一次情報： Jev AIホームページ、Jev AIドキュメント、Jev AI Playground、TypeSafeの紹介