Choice、Score、Noul

プリミティブの選び方

回答がキュー、スキル、クラスラベル、次のリンクなど、名前付きの選択肢1つである場合はChoiceを使います。TypeSafeに表示される質問は「どの選択肢ですか？」です。返されるのは選択結果、確率、confidenceです。基準には最大255件の選択肢をマップで指定できます。Wikipediaリンクが数百件ある場合、1つのChoiceに詰め込むことはできません。Wikiracingデモでは先にスコアを付け、絞り込んだ候補から選択します。

回答が、平静 / 不満 / 非常に不満、または1-5の深刻度など、短い順序付き凡例上の程度ならScoreを使う。戻り値はscore、legend、確率、confidence。Criteriaは2～10段階の順序付き配列となる。scoreを補間して正確な量に換算してはならない。Jev 1.13のレベルでは、2つの段階間にある数値の復元精度が低い。期待値はしきい値判定にのみ使う。

質問がはい／いいえで答えられる場合、つまり「これは正しいか？」にはNoulを使います。0から1のnoulを返します。基準には任意で真と偽の説明を指定できます。confidenceフィールドはありません。0.5に近いNoulは不確実性を示し、中程度の強度ではありません。Noulが2択のChoiceと等価だと仮定したり、一方で調整したしきい値を他方へ流用したりしないでください。TypeSafeのjaggednessページでは、同じチケットについて、返金のNoulが0.22、はいのChoiceが0.01だった例を示しています。

並列質問とID

1つのリクエスト内の質問はstateを共有し、互いに独立して並列実行される。質問を追加してもレイテンシはほとんど変わらない。同じマップ内にChoice、Score、Noulを混在させられる。キーはurgency、department、frustrationなど自由に決められ、対応する回答が同じキーで返る。キーは基盤モデルには送られず、推論にも使われない。

ループ内でキーを生成する場合、このID規則が重要です。jaggednessページの数え上げ例では、リストの各項目につき1つのNoul（item_0, item_1, …）を問い、Pythonで回答を合計します。Jevがこれらの名前をトークンとして認識することはありません。再試行を元のマップと対応付けられるよう、ログ内の名前は固定してください。

すべてのプリミティブ応答に共通する返却メタデータには、requestId、タイムスタンプ、レイテンシ、メタデータが含まれます。トレースの関連付けにはrequestIdを使用します。タイムスタンプとレイテンシは通信上の事実として扱い、再質問の理由にはしないでください。メタデータは中核ペイロードに添付できる任意情報です。まず3つのプリミティブを比較し、その後で型付き回答を包む共通フィールドを確認してください。

実運用上の制限

Choiceの選択肢は255件が厳格な上限で、目安ではありません。WikiracingではScoreで候補を絞り、その後にChoiceを使って上限を回避します。分類体系に400件のラベルがある場合、同じ2段階構成かChoiceの階層化が必要です。APIが256件を受け付けるとは期待しないでください。

Scoreの2～10段階は、人が声に出して読める短い凡例向けだ。100点満点の品質尺度には不適切なので、個別のScoreに分けてコードで加算する。1.4のような段階間のscoreは想定内だが、その小数値から金額を復元する用途には使えない。

Noulにはconfidenceフィールドがないため、ゲートにはnoul値と、追加した別の質問を使います。よくある組み合わせは、「対象範囲内か」を判定するNoulと、noulが高い場合に限り「どの区分か」を選ぶChoiceです。jaggednessの不変条件記録は、この2つの数値を同じ統計量として扱わないよう警告しています。

1つのチケットに対して3種類すべてのプリミティブを混在させるリクエストは、上級テクニックではなく標準的な構成だ。緊急性をNoul、担当部署をChoice、不満度をScoreで判定し、その後をコードで処理する。クイックスタートのcurlにも同じマップが示されている。このページの比較は、JSONを書く前に型を選ぶためのものだ。

共通の外枠フィールドは第4のプリミティブではありません。requestId、タイムスタンプ、レイテンシ、メタデータは呼び出しを追跡できるよう、すべての回答に付随します。製品に関する情報はstateに入れます。ポリシーをメタデータへ詰め込んでいる場合は、Jevが実際に読み取るオブジェクトへ移してください。

Criteriaは、新しく加わったチームメンバーが明日読むつもりで書く。Choiceの選択肢名とScoreのレベル名も質問の一部だ。曖昧なラベルは、字面どおりの解釈が本番環境に現れる原因になる。

Noulは固有名詞である。リクエストの残りが英語の文章でも、表記を変えないこと。