Jev の state の設計: 文字列・オブジェクト・配列の使い分け

state は、Jev に判定させる材料です。問い合わせ文、文章の一節、アプリケーションの現在の状態など、質問の対象になるものをここに入れます。1回のリクエストで評価される state は1つで、すべての質問が同じ state を見ます。

公式の言い方を借りると、専門家の集まりに判断を仰ぐ前に見せる資料が state、仰ぐ判断が質問です。

3つの形

公式の勧めは、たいていの場合はオブジェクトです。各部分に説明的な名前が付き、部分どうしの関係がはっきりします。

比べる材料は、まとめて1つの state に入れる

返金の判断なら、問い合わせ・注文の記録・返金規定を1つのオブジェクトに入れます。会話と注文と規定を含んでいても、これで1つの state です。

{
  "ticket": {
    "subject": "二重請求",
    "messages": [
      { "from": "customer", "text": "注文 A-104 で2回請求されています。重複分を返金してください。" },
      { "from": "support", "text": "請求を確認しています。" }
    ]
  },
  "order": {
    "id": "A-104",
    "charges": [
      { "amount_jpy": 4900, "status": "captured" },
      { "amount_jpy": 4900, "status": "captured" }
    ]
  },
  "refund_policy": "二重請求は返金の対象になります。"
}

判断のために見比べる必要があるものは、同じ state に入れます。

内容は state に、判断は質問に

state には内容と事実を入れ、「何を判断してほしいか」は質問の側に書きます。上の例なら、返金規定は state に置いたうえで、質問を分けます。

• 顧客は返金を求めているか（Noul）
• 記録は二重請求を示しているか（Noul）
• 規定はこの返金を支持するか（Noul）

3つの答えをコードで組み合わせ、自動で処理するか人に回すかを決めます。「この返金を承認すべきか」と1つにまとめて聞くより、どこで判断が割れたかが分かります。

質問から特定の部分を指す

state がオブジェクトのとき、質問の instructions にバッククォートで囲んだパスを書くと、どの部分についての質問かをモデルに伝えられます。

"is_urgent": { "type": "noul", "instructions": "Does `message` convey urgency?" }

配列の要素は items[3]、入れ子は ticket.messages[0].text のようにドットと添字でたどります。

手元で次の state を送り、`message` を名指しして3つの質問をした結果は、Jev とは に載せたとおりです。plan のような、その質問に関係のない項目が混ざっていても、名指しすることで質問の対象がはっきりします。

{ "message": "助けてください！3日前から入金がずっと失敗しています。", "plan": "business" }

配列は「まとめて送る」ための仕組みではない

配列を渡しても、配列全体が1つの state として評価されます。10件のレビューを配列で渡して「これは否定的か？」と聞いても、10個の答えは返ってきません。

要素ごとの判断が欲しいときは、要素の数だけ質問を作ります。公式が「数える」処理の代わりとして示している書き方がこれです。

result = client.system_one(
    {"items": items},
    {f"item_{i}": Noul(instructions=f"Is `items[{i}]` the name of a fruit?")
     for i in range(len(items))},
)
count = sum(result.nouls[f"item_{i}"].noul > 0.5 for i in range(len(items)))

個数をモデルに数えさせず、1件ずつ判定してコードで合計する、という形です。

入れすぎない

入力の上限は、state ＋ 最も長い質問1つで 32k トークン、リクエスト全体で 64k トークンです（料金と制限）。ただし上限に収まっていればよい、というわけではありません。

公式は、state に判断と関係のない内容が増えるほど精度が下がること、大きな state では誤答の原因になった部分を特定しにくくなることを明記しています。

• 先にコードで検索・絞り込みをして、質問に必要な項目だけを送る
• コードで絞れないときは、Noul で「この部分は関係があるか」を先に判定してふるいにかける
• 1つのリクエストに「念のため」の資料を足さない

日本語の state

state の注記にも、学習の主言語は英語で、日本語を含む CJK は受け付けるが現状は精度が下がる、と書かれています。

手元で試した範囲では、日本語の state に英語の質問をしても、日本語の質問をしても、同じ傾向の値が返りました（緊急の問い合わせ文で 0.94、急ぎでない文で 0.05）。ただし数例の結果です。項目名（キー）は英語にしておくと、質問からの名指しが書きやすくなります。日本語の業務データで使う前に、正解の分かっているデータで測ってください。

テキスト以外は先に変換する

画像・音声・動画・バイナリは受け付けません。OCR の結果、文字起こし、抽出した項目など、テキストか構造化データにしてから渡します。数値や色コードのような表現も、意味のある言葉や区分に直してから渡すほうが精度がよい、とされています（Jev が苦手なこと）。