classify

分類

テキストをコンテキストに取り込む前に、classifier.dev を使って分類します。ファイルや検索結果からプログラムで入力を収集し、まとめて送信してから、保持する価値のある項目を読み取ります。すでにコンテキストにある少数の項目については、ユーザーが API の判定を求めない限り、自分で判断してください。どのソースが判定を出したのかを明記します。どちらの API ティアも、呼び出しごとに同一のラベルやスコアが返されることを保証しません。

テキストはマシンからサードパーティの API に送信されるため、公開フォームに貼り付けてもよいテキストだけを送ってください。入力に秘密情報や個人情報が含まれている場合は、同じラベルを使ってローカルで分類し、判定は自分の判断であると明記するか、API による判定が不可欠であれば、情報を伏せた入力を求めてください。

ステップ 1：ラベルを決める

/classify <text> [option, option, option] では、テキストとラベルの両方を指定します。リクエストを作成する前に、単一ラベルでの分類、独立した複数の次元、マルチラベルのタグ付けのいずれかを選んでください。ラベルが指定されていない場合は、各セットに説明的なラベルを 2〜100 個作成します。各ラベルは 200 文字以内です。

単一ラベルで分類する場合は、質問を漏れなく分割するラベルを設定してください。想定されるテキストはすべて、必ずいずれか 1 つのラベルに分類される必要があります。話題から外れた入力に備えて none of these を、不十分な証拠に備えて unknown を追加します。各次元にも同じ考え方を適用してください。マルチラベルのタグは重複してもかまいません。

ユーザーがラベルを指定しなかった場合は、レポートに選択したラベルを記載します。

instructions は最大 4,000 文字まで指定でき、曖昧な基準を定義するために使います。判定によって不足しているカテゴリや不明瞭な基準が明らかになった場合は、基準を修正し、その変更を説明してください。結果を比較する際は基準を固定してください。望ましい回答が得られるまで再実行すると、結果に偏りが生じます。

ステップ 2：呼び出す

content-type: application/json を指定して POST https://classifier.dev を使用します。通常の自由記述テキストのリクエストにキーは不要ですが、匿名プロキシ経由のトラフィックでは、資金を入れたワークスペースキーが必要になる場合があります。形式に応じてリクエストボディを選びます。

用意するもの	リクエストボディ
1つのテキスト、1つのラベルセット	{"input":"…","labels":["a","b"]}
最大1,000件のテキスト、1つのラベルセット	{"inputs":["…","…"],"labels":["a","b"]}
複数のラベルセットを使ったテキストの一括分類	{"items":["…"],"dimensions":{"topic":["a","b"],"urgency":["low","high"]}}
テキストまたはバッチに該当するすべてのタグ	{"inputs":["…"],"labels":["a","b"],"multi":true,"max_labels":2}

input、inputs、items のいずれか1つだけを使用します。ディメンションを指定する場合はトップレベルの labels を置き換えるため、multi または max_labels と併用できません。特定のディメンションに固有の基準を設定するには、そのラベル配列を {"labels":["a","b"],"instructions":"…"} に置き換えます。

デフォルトでは tier: "fast" を使用します。単一ラベルの判定にサーバー側でのレビューが必要な場合は smart を選びます。信頼度が 0.7 未満の回答を、ディメンションごとに独立して推論モデルで再判定します。エスカレーションされた回答には escalated: true、信頼度とスコアの値は null、説明には unscored が設定されます。エスカレーションに失敗した場合は元の回答が維持され、usage.escalation_failed に記録されます。マルチラベルリクエストでは tier が無視されるため、fast を使用してください。

JSON エンコーダーでリクエストボディをシリアライズし、--data-binary @- を指定して標準入力から curl に渡します。引用符やコマンド置換がデータとして保持されるよう、入力テキストをシェルコマンド文字列に含めないでください。項目ごとに1回ずつ呼び出すのではなく、以下の上限内でバッチ処理してください。

通常のテキスト処理では、入力あたり最大32,000文字、リクエストボディは最大1 MB、入力は最大1,000件、ディメンションは最大20個です。また、ディメンションの判定は入力数とディメンション数の積で数え、最大1,000件です。公開されている smart リクエストでは、入力またはディメンションの判定数は最大200件です。

IPごとの無料枠は、HTTP 呼び出し数ではなく分類数をカウントします。単一ラベルの入力を400件まとめたバッチは、分類400件としてカウントされます。ディメンションでは判定ごとにカウントされます。

tier	1分あたり	1日あたり
fast	3,000	20,000
smart	200	2,000

バッチ全体が残りの割り当て枠に収まる必要があります。共有ラベルセットの割り当て枠や利用上限によって、これらの上限に達する前にリクエストが拒否される場合があります。より長いテキスト、有料処理、または割り当て枠の詳細については、リクエスト方法を決める前に最新の API リファレンスを確認してください。デフォルトモデルでより長い入力を処理するには、資金を入れた fast tier の長文コンテキスト処理が必要です。テキストを保持し、黙って切り詰めないでください。

失敗した場合は、ステータスと、存在する場合は JSON の error、code、action、retryable フィールドを確認します。不正なリクエストは修正してください。資金またはアクセスに関する制限は、その旨を報告してください。最初に発生した失敗の種類にかかわらず、リクエストの再試行は全体で最大1回とします。429 の場合は Retry-After に従い、遅延が秒単位のときのみ再試行します。一時的なネットワーク障害または 5xx エラーの場合は、再試行の前にバックオフし、Retry-After が指定されていればそれに従います。HTML エラーが返された場合は、ステータスと、利用可能であればリクエスト ID を報告します。それでもリクエストが失敗する場合は実際の原因を報告し、可能であれば同じラベルを使ってローカルで判断します。その場合は、自身の判断であることを明記し、信頼度を捏造しないでください。入力をローカルで確認できない場合は、どの入力が未分類のままかを報告します。

ステップ 3：判定を報告する

results[i] を元の入力順に対応させ、モードに応じて読み取ります：

モード	結果のフィールド
単一ラベル	results[i].label、.confidence、.scores
次元	results[i].dimensions[name].label、.confidence、.scores
マルチラベル	results[i].labels と .scores。単一の label や confidence はありません

しきい値を使う前に、fast の場合も含めて、confidence とスコアが null でないことを確認してください。confidence が null の場合は unscored と報告し、confidence ゲートが必要なときはレビューに回します。数値の confidence が 0.7 未満の場合は、判定に「弱い」とフラグを付けます。スコアは指定されたラベル間の選択肢を示すものであり、カテゴリへの適合性を確立したり、正しさを証明したりするものではありません。エスカレーションやフォールバックの回答を追跡できるよう、結果とともに提供時の model を保持します。

マルチラベルの結果には、スコアが 0.7 以上のタグが高い順に記載され、max_labels が指定されている場合はその上限で制限されます。各タグはスコアとともに報告します。呼び出し元が別のしきい値を指定した場合は、スコアの全マップを使用します。タグが空のリストになることも、有効な結果です。

フィルタリングでは、残す方向に偏らせます。否定的な判定とは、呼び出し元が破棄側として指定したラベル（irrelevant、none of these）です。ラベルが 2 つを超える場合は、フィルタリングの前にどのラベルを破棄するか尋ねてください。呼び出し元が指定するまでは、すべての項目を残します。呼び出し元がしきい値を指定していない場合は、数値の confidence が 0.8 以上の否定的な判定のみを破棄します。肯定的な項目、confidence が低い項目、スコア未評価の項目は、確認またはレビューのために残します。マルチラベルのフィルタでは、呼び出し元が指定したタグのルールを該当するスコアに適用し、判断が不確かな項目は残します。

JSON ではなく、判定を報告してください。1 件のテキストは 1 行（label · 0.94）で示します。バッチの場合は、表またはラベルごとにまとめた項目を示します。呼び出し元がフィルタリングを求めた場合は、残した項目と破棄した件数を示します。

このスキルをメンテナンスする際は、リクエストとレスポンスのルールを、公開されている上流のスキルおよび最新の API リファレンスと照合してください。