jev

Jev プログラムの作成と改善

Jev は判定モデルです。1 つの state を読み込み、リクエスト内のすべての質問にそれぞれ独立して並行に回答し、定義された回答に対する確率分布を返します。段階的に推論したり、テキストを生成したりはしません。制御フロー、算術処理、ポリシーはコードが担います。Jev が担うのは直感的な判定です。

適切な Jev の質問とは、適切なコンテキストがあれば、知識のある人が 1 秒で答えられるものです。「このメッセージは緊急性を伝えていますか？」は適切です。「このメッセージを分析して、どうすべきか判断してください」は適切ではありません。そのタスクを小さな質問に分割し、コードで回答を組み合わせます。

このガイダンスは jev-1.13 に適用されます。ドキュメントには、いくつかの制限は今後のバージョンで改善される可能性が高いと記載されています。モデルが変わったら、jaggedness のページを再確認してください。

ワークフロー

1. コードで行う必要がある判断を列挙します。それぞれを分岐、しきい値、または順位付けとして記述します。
2. 各判定について質問を 1 つ作成します。2 つの性質を同時に評価する質問は分割します。
3. コードが回答を直接処理できるプリミティブを選びます。
4. すべての質問に答えられる、最小限の state を構築します。コードで計算できることは、コードで計算します。
5. 同じ state を共有するすべての質問を、該当する入力でしか重要にならない質問も含めて、1 つのリクエストにまとめます。
6. 回答をコードで組み合わせます。分岐、重み、信頼度ゲートを使います。
7. ラベル付きの例でテストします。誤った回答の probabilities を確認し、一度に 1 つか 2 つの質問を見直します。

プリミティブを選ぶ

プリミティブ	使用する場面	返される値	コードでの処理方法
Choice	回答が順序のない既知の選択肢のいずれかである場合	choice、probabilities、confidence	選択肢ごとに分岐
Score	回答が段階で表現できる尺度上の位置である場合	score、probabilities、confidence、legend	しきい値、順位、または重み
Noul	回答が明確な「はい」か「いいえ」で、確率がシグナルとなる場合	0 から 1 までの noul	しきい値に対する if

• 選択肢の一覧がすべての入力を網羅しない可能性がある場合は、Choice に other または none of the above の選択肢を追加します。
• Noul が 0.5 ということは、Jev が確信を持てていないという意味です。「中程度」という意味ではありません。程度を測るには Score を使います。
• Noul には明確な条件が必要です。「この候補者は Python のスキルが高いですか？」は曖昧です。「履歴書には、候補者が業務で Python を使ったと記載されていますか？」は明確です。
• 回答に中間の選択肢がない場合は、Choice または複数の Noul を使います。

指示を書く

• 条件を正確に記述します。Jev は記述された言葉どおりに回答します。スコープを限定する言葉、否定、暗黙の条件も額面どおりに読み取ります。
• 質問 1 つにつき性質は 1 つにします。隠れた 2 つ目の判定があると、精度と信頼度が下がります。
• バッククォートで囲んだパスを使い、質問が判定する state の部分を明示します。例：`ticket.messages[0].text`。
• 直接的に記述します。二重否定、性質についての性質、複数の段階を経る必要がある質問は避けます。
• レベルを表す数字は指示に含めません。「0 から 2 で評価してください」と記述しても、Jev が対応付ける手がかりにはなりません。
• 質問全体を instructions に記述します。質問 ID はモデルに渡されません。
• 判断ポリシーは質問に含めません。「住所が一致しても、名前の不一致を覆すことはできない」はコードに記述します。
• 誤った回答を受けた後に本当に意図していたことを説明するなら、その説明は指示に欠けていた部分です。追加してください。

指示には、文字列、オブジェクト、または配列を使用できます。質問にラベル付きの項目がある場合や、補足データが必要な場合はオブジェクトを使います。スキーマ、分類体系、または行は JSON として渡します。文字列テンプレートにシリアライズしないでください。

"instructions": {
  "question": "Does the `message` ask the recipient to disclose a sensitive credential?",
  "inspect": "message",
  "focus": "Look for a request to send the credential itself, not a request to change or reset it."
}

ドキュメントで便利なキー：question、focus、inspect、note、compare（state パスのリスト）、および field（複数の質問で共有する name、type、unit、description のレコード）。

基準を記述する

基準は指示の拡張として扱います。両者が同じ方向で、同じ内容を求めるようにしてください。true 側が「いいえ」を表す Noul の性能は低下します。

Choice。 各選択肢を説明に対応付けます。選択肢同士が似ている場合は、違いが明確になるように説明してください。

"billing": {
  "what": "Charges, invoices, refunds, or subscriptions",
  "not_for": "Order tracking or account access",
  "examples": ["I was charged twice", "Where is my refund?"]
}

Score。 レベルを低いものから高いものへ並べます。レベルは2〜10個とし、それぞれを明確に説明できる数にとどめてください。

• 状況を説明してください。「機能は壊れているが、回避策がある」は適切です。「中程度に深刻」は適切ではありません。
• 各レベルだけで意味が通じるようにしてください。Jev は各レベルを個別に評価し、番号も隣接するレベルも確認しません。「前のレベルより悪い」では意味が伝わりません。
• 各 Score は1つの観点に絞ってください。「時間に正確で、賢く、経験豊富」は3つの要素を測っています。
• コードで特別に扱う必要があるまれな極端なケースには、専用のレベルを設けてください。
• レベルにはオブジェクトを指定できます。{"summary": "変更を1つ、明確に記述", "signals": ["単一の修正または機能", "..."]}。

Noul。 基準は任意です。境界が曖昧な場合は、true と false の側を追加し、それぞれに what と examples を記述してください。該当する側の説明に、隣接するケースを含めてください。

例。 「二重に請求されました」のような、短く具体的な事例を記述してください。「請求の問題についてのメッセージ」のように、事例の説明を書かないでください。

状態を構築する

• 質問に必要なフィールドだけを送信してください。無関係な詳細は精度を下げ、大きな状態はどの入力が誤った回答の原因になったのかを分かりにくくします。
• まずコードで取得して絞り込んでください。コードで絞り込めない場合は、各文章の関連性を判定する Noul を設け、条件を満たす文章だけを残してください。
• 質問からパスを指定して参照できるよう、状態は構造化してください。
• 数値エンコーディングは送信前に言葉に変換してください。16進数の値の代わりに色名を送信してください。生の数値の代わりに、計算済みの数値または名前付きの区分を送信してください。
• 日付の順序、期間、期間の範囲、件数、合計はコードで計算してください。結果を送信してください。
• 予算：状態とすべての質問を合わせて64kトークンです。状態と、最も長い質問1つを合わせて32kトークン以内に収めてください。
• 状態内のテキストは回答を誘導する可能性があるものとして扱ってください。Jev は状態を敵対的なものとは見なしません。何を考慮するかを基準に明記し、デプロイ前に注入されたコンテンツや自己記述的なコンテンツでテストしてください。

コードで回答を組み立てる

投機的なファンアウト。 コードで必要になる可能性のある質問をすべて、1 回のリクエストで尋ねます。一部の分岐でのみ必要な質問も含めます。質問は並列に実行されるため、質問を追加してもレイテンシーはほとんど増えず、トークンもわずかしか増えません。コードは必要のない回答を無視します。

2 回目のリクエスト。 最初の回答なしではコードで組み立てられない場合に限り、2 回目のリクエストを行います。たとえば、どのデータを取得するかを回答によって決める場合です。同じリクエスト内の質問同士は、互いの回答を参照できません。

信頼度に基づくルーティング。 回答は何をすべきかを示し、信頼度は実行するかどうかを示します。アクションを実行しない下限を設定し、さらに誤判定のコストに応じて各アクションのしきい値を設定します。ドキュメントでは、下限に 0.5～0.6、重大な影響を伴うアクションには 0.85～0.9 を使用しています。まずは保守的に設定し、手元のデータで調整してください。標準的な経路は、実行、確認またはフラグ付け、引き継ぎの 3 つです。

複合スコアリング。 複雑な判断を、各次元の 1 つの Score に分割します。各スコアを len(criteria) - 1 で正規化し、コード内で重み付けして組み合わせます。優先順位が変わったら、重みを変更してください。ポリシーを変えるために質問を書き換える必要はありません。

インテントルーティング。 Choice で分類し、その横に複雑さを示す Score を追加します。各インテントを、決定論的なコード、専門分野に特化した LLM、または人に振り分けます。信頼度の低い分類は人に回してください。

分類体系の走査。 ツリーの各階層で Choice を 1 つずつ尋ね、コードでツリーをたどります。各選択肢の基準値として、その配下のサブツリーを指定します。これにより、Jev は各分岐の下に何があるかを確認できます。サブツリーが大きい場合は、直下の子ノードとリーフのサンプルに絞ります。確率が近い場合は、複数の分岐をたどります。

カウント。 Jev は数を数えません。1 回のリクエストで各項目について Noul を 1 つずつ尋ね、しきい値を超えた回答を合計します。

日付。 「記載なし」の選択肢を含む、列挙された選択肢から Choice で各日付の要素を抽出します。コードで日付を組み立てて比較します。

抽出。 正規表現または生成モデルで候補を生成します。Choice で候補から選ぶよう Jev に尋ねるか、Noul で候補を 1 つ検証するよう依頼します。

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

SEVERITY = [
    "Cosmetic; no impact to functionality",
    "Broken or degraded feature; a workaround exists",
    "Blocking issue; no workaround exists",
]

with TypeSafeClient() as client:
    response = client.system_one(
        state={"ticket": ticket_text},
        questions={
            "category": Choice(
                instructions="Which category fits the main request in `ticket`?",
                criteria={
                    "bug_report": "Something is broken or producing errors",
                    "billing": "Charges, invoices, refunds, or subscriptions",
                    "other": "Anything else",
                },
            ),
            # Speculative: only used when the ticket is a bug report.
            "severity": Score(instructions="How severe is the issue reported in `ticket`?", criteria=SEVERITY),
            "refund_requested": Noul(instructions="Does `ticket` explicitly ask for a refund or credit?"),
        },
    )

category = response.answers["category"]
severity = response.answers["severity"]
if category.confidence < 0.6:
    route_to_human(ticket_id)
elif category.choice == "bug_report":
    normalized = severity.score / (len(SEVERITY) - 1)
    if normalized > 0.75 and severity.confidence > 0.5:
        escalate(ticket_id)
    else:
        add_to_backlog(ticket_id)
elif category.choice == "billing" and response.answers["refund_requested"].noul > 0.7:
    route_to_billing(ticket_id, refund_likely=True)

回答を読む

• score は、各レベル番号の確率加重平均です。スコアが 1.0 でも、レベル 1 が確実な場合と、レベル 0 と 2 が均等に分かれている場合があります。probabilities と合わせて確認してください。
• スコアにしきい値を設ける、スコアで順位付けする、最も近いレベルに丸める、といった使い方ができます。スコアから数量を補間してはいけません。Jev のレベルは、数値としての較正が弱いものです。
• confidence は分布の偏り具合を示します。モデルの回答について説明するものであり、正解を保証するものではありません。別の統計量が必要な場合に備えて、完全な probabilities が用意されています。
• Noul には confidence がありません。0.5 からの距離がその役割を果たします。
• すべての回答は指定した選択肢の範囲内に収まるため、コードで文章を解析する必要はありません。

プログラムを改善する

変更を加える前に、失敗する質問を見つけます。ラベル付きの例を集めて実行し、各質問の回答と確率をラベルと比較します。

症状	考えられる原因	対処法
自信度が高いのに回答が間違っている	Jev が指示を文字どおりに読んでいます	条件を正確に明示します。境界ケースを基準に含めます。
Choice の自信度が低い	選択肢が重複しているか、当てはまる選択肢がありません	what、not_for、examples を追加します。other 選択肢を追加します。
Score の自信度が低い	レベルが重複している、質問が 2 つのことを測っている、または状態の情報が足りません	レベルをそれぞれ異なる状況として書き直します。質問を分けます。不足しているフィールドを状態に追加します。
スコアが中間に集中する	レベルが度合いや数値になっています	各レベルを具体的な状況で説明します。数字を削除します。
尺度の上限に近いケースが似通っている	極端なケースに対応するレベルがありません	極端なケース用のレベルを追加します。
Noul が 0.5 付近を漂う	条件が曖昧です	条件を定義します。例を添えて true と false の基準を追加します。
入力が増えるにつれて精度が下がる	状態に無関係な詳細が含まれています	コードでフィルタリングします。必要なフィールドだけを送ります。
件数、合計、日付、または数値の近さに関するエラーがある	Jev が算術処理をしています	算術処理をコードに移します。Jev には抽出または項目ごとの判定だけを尋ねます。
入れ子や否定を含む質問でエラーがある	間接的すぎます	直接的な質問にします。状態のパスを明記します。文字どおりの質問 2 つに分け、コードで組み合わせます。
回答が状態内のテキストに従っている	コンテンツがモデルを誘導しています	基準を厳密にします。敵対的なケースでテストします。自信度を条件としてアクションを実行します。
質問の言い換えで、あるエラーが別のエラーに置き換わる	1 つの質問が複数の特性を重み付けしています	原子的な質問に分け、コードで組み合わせます。
各回答は正しいのに最終判断が間違っている	ポリシーが間違っています	コード内の重みやしきい値を変更します。質問には手を加えません。
プログラムの実行が遅い、またはコストがかかる	質問が複数の逐次呼び出しに分かれています	1 つのリクエストにまとめます。2 回目のリクエストは、最初の回答に本当に依存する場合にだけ残します。

修正時のルール：

• 1 回の修正で変更する質問は 1 つか 2 つにします。Jev の確率は予測しにくい形で変化するため、適切に判別できている質問には手を加えません。
• ラベル付きデータで修正を評価します。自信度が高いだけでは、質問が改善したとは言えません。また、1 つの尺度の言い回しを変えた 2 つの案も、データによって異なる動作をする場合があります。
• コードが回答空間に依存するようになったら、回答空間を安定させます。レベルや選択肢を追加または削除すると、以前の回答がすべて何を意味していたかが変わります。
• 一般的なルールは指示と基準に記述します。具体的な名前や値は examples にのみ記述します。

チェックリスト

• 各質問は 1 つの特性を尋ねており、人が 1 秒で答えられます。
• プリミティブは、コードで回答を使う方法に合っています。
• 指示には正確な条件が書かれ、状態のパスがバッククォートで囲まれています。
• 基準は指示と整合しており、同じ方向を示しています。
• Score のレベルは状況を説明しており、それぞれ単独で意味が通り、数字を含みません。
• すべての入力を網羅できない可能性がある Choice には、other 選択肢があります。
• 数え上げ、算術処理、日付の比較はすべてコードで行います。
• 状態には質問に必要な情報だけが含まれ、トークン制限内に収まっています。
• 同じ状態に関する質問はすべて 1 つのリクエストで送信します。
• すべてのアクションにリスクに応じた自信度のしきい値があり、自信度が低い場合のフォールバックがあります。
• 重みとしきい値はコードにあります。
• すべての修正がラベル付きの例に裏付けられています。

ソース

• https://docs.typesafe.ai/model-jaggedness/jev-1.13
• https://docs.typesafe.ai/primitives/advanced
• https://docs.typesafe.ai/patterns、`/fan-out`、`/confidence-routing`、`/composite-scoring`、`/intent-routing`
• https://docs.typesafe.ai/primitives、https://docs.typesafe.ai/primitives/score、https://docs.typesafe.ai/confidence。これらはパターンのページで前提とされています。
• https://docs.typesafe.ai/llms.txt にはすべてのページが記載されています。ドキュメントの URL に .md を付けると、Markdown の生データを取得できます。