AiHubMixでJevを呼び出す方法：構造化分類チュートリアル

短い回答： jev-1.13 はテキストを生成しません。テキストの一部と一連の名前付き質問を https://aihubmix.com/v1/systemone にPOSTすると、質問名に基づいたタイプ付きの回答が返されます — カテゴリ、スコア、または確率です。解析する必要はありません。以下に、動作するリクエスト、完全なレスポンス形式、および静かに精度を損なう1つの設計ミスを示します。

Jevの用途

段落ではなく、判断が必要なときに使用します：サポートチケットのルーティング、重大度のスコアリング、緊急性のフラグ付け、コンテンツのゲーティング。モデルページには明確に記載されています — 「テキスト生成なし、解析する必要なし。」

説明、要約、または自由形式の出力が必要な場合は、通常のチャットモデルを使用してください。jevはそれを生成できません。

始める前に

• [ ] Python 3がインストールされている（標準ライブラリで十分です）
• [ ] AiHubMixアカウントとAPIキー
• [ ] キーは AIHUBMIX_API_KEY としてエクスポートされていること、ソースにハードコーディングしないこと

OpenAI SDK、LangChain、または requests パッケージは必要ありません。

ステップ 1 — エンドポイントを知る

POST https://aihubmix.com/v1/systemone
Authorization: Bearer YOUR_KEY
Content-Type: application/json

これはモデル固有のルートであり、ではありません /v1/chat/completions。OpenAI互換のクライアントはこれを呼び出すことができません。プレーンHTTPを使用してください。

ステップ 2 — 質問の種類を選択する

3種類あり、1つのリクエストで自由に組み合わせることができます：

ステップ 3 — リクエストを構築する

state は判断されるテキストです。 questions のキーはあなたが考案した名前です；レスポンスは同じ名前を使用します。

payload = {
    "model": "jev-1.13",
    "state": "こんにちは、3日間Stripeアカウントを接続しようとしていますが、"
             "失敗し続けています。売上を失っています。できるだけ早く助けてください。",
    "questions": {
        "department": {
            "type": "choice",
            "instructions": "どのチームがこれを処理すべきか",
            "criteria": {
                "billing":   "支払いまたはサブスクリプションの問題",
                "technical": "バグまたは統合の問題",
                "sales":     "価格またはアカウントの質問",
            },
        },
        "frustration": {
            "type": "score",
            "instructions": "顧客がどれほどフラストレーションを感じているか",
            "criteria": [
                "冷静で、事実を述べている",
                "フラストレーションを感じているが、礼儀正しい",
                "非常に怒っていて、強い言葉を使っている",
            ],
        },
        "is_urgent": {
            "type": "noul",
            "instructions": "メッセージが緊急性や時間的な敏感さを伝えているか",
        },
    },
}

ステップ 4 — 標準ライブラリで送信する

import json, os, urllib.error, urllib.request

def ask(payload):
    req = urllib.request.Request(
        "https://aihubmix.com/v1/systemone",
        data=json.dumps(payload).encode(),
        headers={"Authorization": "Bearer " + os.environ["AIHUBMIX_API_KEY"],
                 "Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=60) as r:
            return json.loads(r.read())
    except urllib.error.HTTPError as e:
        raise SystemExit(f"HTTP {e.code}: {e.read().decode(errors='replace')[:500]}")

リクエストの構築は関数内に保ってください。モジュールレベルで構築して送信すると、ファイルをインポートするたびに呼び出しが再実行され、トークンを消費します。

ステップ 5 — 回答を読む

各回答はその type に一致するキーの下に値を格納しますので、1つのアクセサで3つすべてをカバーできます：

data = ask(payload)
for name, ans in data["answers"].items():
    kind = ans["type"]
    print(name, kind, ans[kind], ans.get("confidence"))
print("usage:", data.get("usage"))

確認済みの出力：

department   choice  billing   0.51
frustration  score   1         1
is_urgent    noul    1         None
usage: {'input_tokens': 424, 'output_tokens': 73}

ステップ 6 — 完全なエンベロープを理解する

プリントループは有用なフィールドを隠しています。 score 回答の生のJSON：

{
  "type": "score",
  "score": 1,
  "legend": {"0": "冷静で、事実を述べている", "1": "フラストレーションを感じているが、礼儀正しい", "2": "非常に怒っていて、強い言葉を使っている"},
  "probabilities": {"0": 0, "1": 1, "2": 0},
  "confidence": 1
}

• legend はインデックスをあなた自身の言葉にマッピングします — 整数は自己説明的であるため、コード内にルックアップテーブルは必要ありません。
• probabilities は完全な分布を提供し、近い引き分けを検出するのに役立ちます。
• noul には confidence フィールドがありません。 その確率が信号です。

トップレベルはまた、 usage 、 id 、 provider （TypeSafe）、および解決されたバックエンドバージョン typesafe/jev-1.13-20260917 を返します。

精度を損なうミス

上記のリクエストでは、 department が billing を 0.51 の信頼度で返しました。同じリクエストを繰り返すと、同じラベルが 0.38 で返されました — 答えは安定していましたが、示された確実性はそうではありませんでした。

原因は基準にあり、モデルにはありません。 billing は「支払いまたはサブスクリプションの問題」であり、 technical は「バグまたは統合の問題」です。失敗し続けるStripeの統合 は、実際に両方に一致します。モデルは、スキーマに書かれたあいまいさを報告していました。

本番前の2つのルール：

1.  choice 基準は相互に排他的であるように記述してください。人間が2つのラベルの間でためらう場合、モデルもそうします。
2. 信頼度の閾値を設定し、低信頼度の結果を受け入れるのではなく、人間のキューにルーティングしてください。不確実性を認めるモデルは、隠すモデルよりも価値があります。

プレローンチチェックリスト

• [ ] 環境から読み込まれたキーまたはVCSが無視する 600 モードのファイル
• [ ] choice 基準の重複を確認
• [ ] 信頼度の閾値を定義し、それ以下のフォールバックパスを設定
• [ ] noul の回答は別に処理 — それには confidence がありません
• [ ] 使用されていない質問を削除（3つの質問は424の入力トークンを消費；2つは355を消費）
• [ ] 生のボディで非2xxレスポンスをログ

FAQ

OpenAI SDKを使用できますか？ いいえ。 /v1/systemone はOpenAI互換のルートではありません。

jevは文や要約を返すことができますか？ いいえ。定義したタイプ付きの質問にのみ回答します。

リクエストごとにいくつの質問ができますか？ 確認済みのテストでは2つと3つを使用しました。各質問は入力および出力トークンを追加するため、実行するものだけを含めてください。

バージョンエイリアスはありますか？ モデルページには jev-latest エイリアスが jev-1.13 とともにリストされています。再現性が重要な場合は、明示的なバージョンを固定してください。

コストはどのくらいですか？ モデルページには $0.0462 / M の入力トークンと $0 / M の出力トークンが公開されています。これらはベンダーの数字です — 予算を立てる前に現在の価格を確認してください。

コンテキストウィンドウは何ですか？ モデルページは一貫性がありません：ヘッダーでは64K、プロバイダーテーブルでは32Kです。どちらかに依存する前に、あなた自身の最長入力に対して確認してください。

このガイドの範囲

上記のすべては、単一の入力に対して3回のライブコールで確認されました。レイテンシ、バッチ処理、スループット、または例と異なる入力での動作はカバーしていません。信頼度の漂流は再現された観察であり、測定されたエラーレートではありません — 閾値を設定する前に、あなた自身のデータで繰り返してください。

AiHubMixを始める

jev-1.13 はAiHubMixを通じて利用可能であり、モデルページにはこのチュートリアルで参照されたすべての情報が含まれています： /v1/systemone エンドポイント、3つの質問タイプとその criteria 形式、完全なレスポンスフィールド、および $0.0462 / M の入力トークンと $0 / M の出力トークンの公開価格。 jev-latest エイリアスは最新のリリースに解決されるため、バージョンが移動しても最新の状態を保ちます。

ここから始めてください：https://aihubmix.com/model/jev-latest

次のステップ：

1. AiHubMixアカウントを作成し、APIキーを生成する
2. ステップ3からリクエストをコピーし、ステップ4から ask() 関数をコピーする
3.  state を自分のキューからの実際のレコードに置き換える
4. 結果を、今日そのレコードをどのように分類しているかと比較する

このガイドが役に立った場合は、構造化出力モデルと分類パイプラインに関する今後の投稿に登録してください。