トラブルシューティング

BudgetExceeded

item_costs、overflow_tokens、exceeded_at_item_id、available_strategies、partial_manifestを確認します。予算を増やす、承認後にコンテンツを明示的に降格する、安全なTextの切り詰めを有効化する、またはモデル呼び出しを中止してください。予算超過からの復旧を参照してください。

PolicyViolation

rule_id、reason_code、item_id、boundaryを確認します。任意項目なら除外される場面でも、必須項目では例外になります。アプリケーション側で承認を判断せずに例外を捕捉し、同じ項目をより弱い境界から再送してはいけません。

UnsupportedContent

v0.1系列のBinaryは、保存とラウンドトリップ専用です。任意／優先のBinary項目はマニフェストの除外項目に記録され、必須のBinary項目はパッキング時に例外になります。アプリケーションが承認した手順でのみコンテンツを変換するか、パックの外に保持してください。

SchemaError

主な原因は次のとおりです。

  • ContextItemを直接構築したときの空のID。

  • 正規化されたコンテンツと一致しないcontent_hashを指定した。

  • min_tokensが負の値。

  • タイムゾーン情報を持たないdatetimeオブジェクトをContextItemへ直接渡した。

  • select()または集約によってidかpayloadが削除された後に、AI固有の操作を実行した。

有効なコンテキスト項目ではなくなった探索用テーブルには、collect()ではなくcollect_records()を使用してください。

PluginError

ランカーは項目ごとに1つの数値スコアを返す必要があります。Pythonトークナイザーは入力文字列ごとに1つの非負整数を返す必要があります。プラグインの結果が変わり得る場合は、フィンガープリントも変更してください。

概算トークン数

profiles.approximate()は常に概算です。バイナリwheelにはo200k_baseとcl100k_base用のネイティブRustトークナイザーが含まれますが、プロバイダーのエンベロープコストを保守的に見積もるため、profiles.openai()もestimated=Trueを返します。これらのネイティブ経路では、Pythonのtokenizers extraは不要です。

Arrow、pandas、Polarsがない場合

必要な連携だけをインストールします。例：

uv add "cognoxium[arrow]"

または：

python -m pip install "cognoxium[arrow]"

未信頼コンテンツが意図せず選択された

untrustedはラベルであり、自動的な拒否を意味しません。外部向けパッキングには出所情報が必要ですが、それ以外の理由では許可されます。信頼境界とポリシーに示すquarantine()またはカスタムポリシーを使用してください。

実行ごとにマニフェストが異なる

安定したidとcreated_atを指定し、入力順を維持し、Cognoxiumのバージョンを固定してください。同じトークンプロファイルのフィンガープリントを使用し、プラグイン設定も固定します。既定値ではUUIDと現在時刻が使われます。