プロバイダーのプロトコルとモデルインターフェース

Anyy v0.1.107は、五種類のネイティブ会話プロトコルに対応しています。共通の動作は、Pi v1.2.0の固定コミット06a466935536f8c9bcacb2d5efc0fc021be1bdffに従います。これはプロトコルとインターフェースの対応範囲を示すものであり、すべてのプロバイダーのエンドポイント、アカウント、認証方式を実環境で検証済みであるという保証ではありません。

会話プロトコル

Anyyのapi_mode	対応するPi API	リクエスト形式
openai-compatible	openai-completions	OpenAI形式のChat Completions。互換性のあるローカルサービスを含む
openai-responses	openai-responses	OpenAI Responses
codex-responses	openai-codex-responses	CodexサブスクリプションのResponsesと、そのトランスポート／セッション動作
anthropic-messages	anthropic-messages	Anthropic Messages
google-gemini	google-generative-ai	Gemini Generative AI

同じブランドのプロバイダーでも、複数のエンドポイント仕様を提供する場合があります。ブランドを選んだだけで、それらを相互に置き換えて使えるようになるわけではありません。OllamaとOllama Cloudは、既存のOpenAI互換形式を使います。Ollamaの/api/tagsはモデルの検出専用です。

Piにある追加の五種類のAPI、azure-openai-responses、bedrock-converse-stream、google-vertex、mistral-conversations、pi-messagesは、このリリースでは独立したネイティブ実装や適合性検証を行っていません。互換ゲートウェイが、実装済みの五種類のいずれかの仕様を実際に満たす場合は、その形式を使えます。ただし、そのサービス固有のネイティブAPIが追加されるわけではありません。ネイティブのAzureやBedrock経路など、設定で無効になっている選択肢は引き続き利用できません。

エンドポイントと認証の詳細

選択したエンドポイントが要求するAPIルートを使います。ネイティブのAnthropic Messagesは、指定したBase URLの既存のプレフィックスを削除せず、/v1/messages?beta=trueを末尾に追加します。Anthropicの直接サービスのルートはhttps://api.anthropic.comです。/v1を重ねて追加しないでください。独自のプロキシは、結合後のパスに対応する必要があります。

Anyyは、プロバイダーへのリクエストを準備する前に認証情報を解決します。ネイティブのAnthropic認証は、有効なキーと、ネイティブのヘッダー／beta規則に従います。auth_transportは、ネイティブMessagesに別の認証方式を強制するスイッチではありません。OAuth／サブスクリプションの設定も、エンドポイントごとに異なります。Codexでは専用のサブスクリプション認証情報を使い、プロバイダーのクライアントを名乗らず、Anyyのクライアント識別情報（既定はoriginator: anyy）を送ります。設定済みのモデルヘッダーを適用してからリクエストヘッダーを適用するため、リクエストヘッダーでこの識別情報を上書きまたは削除できます。認証と、Anyyであることを正しく示すUser-Agentは、引き続きAnyyが管理します。

型付きモデルカタログ

モデルカタログは、typeによって操作を区別します。

型	用途	適用範囲
chat	会話とツール呼び出し用のモデル	type省略時の既定値。主モデル／フォールバックの会話モデル選択に使う
image	型付きの画像生成	models.generateImages()で使う
classifier	構造化された選択、スコア、真偽値の分類	models.classify()で使う

モデルIDは、プロバイダーと型を組み合わせて解決します。同じIDが異なる型に存在する場合がありますが、画像や分類の項目が暗黙に会話モデルへ変わることはありません。カタログの記述情報には、API、入出力モダリティ、制限、料金、互換性のメタデータ、設定済みのサンプリング制御が含まれます。これらの宣言はルートを記述するものであり、リモートサービスの利用可否を検査するものではありません。

高度なproviders[].models[]のフィールドには、type、api、base_url、input、output、headers、input_limits、sampling_params、sampling_params_by_thinking_level、compat、capabilities、costがあります。宣言された通信仕様と、サービスの文書に記載されたパラメーターを使ってください。ネイティブのサンプリング設定は、モデルの既定値、実際の推論レベルのパラメーター、リクエストパラメーターの順にマージし、後のフィールドが前の値を上書きします。これらの制御によって新しいプロトコルが追加されたり、リモートのエンドポイントが任意のオプションを受け付けることが保証されたりするわけではありません。

CodemodeのModelsヘルパー

CodemodeでModelsヘルパーが利用できる場合、次の非同期関数は、同じ設定済みカタログと認証情報を使います。

関数	結果
models.getModelsOfType(type, provider?)	chat、image、classifierのカタログ項目
models.getAvailableOfType(type, provider?)	プロバイダーの有効化状態と、解決可能な認証情報で絞り込んだ項目
models.getModelOfType(type, provider, id)	完全に一致する項目。存在しなければundefined
models.classify(model, context)	型付きの分類結果
models.generateImages(model, context)	型付きの画像結果

「Available」は、ローカルで認証情報と有効化状態を確認した結果であり、実環境での推論テストではありません。スクリプトには、設定済みヘッダーを含まないカタログの記述情報が渡されます。実行時には元の設定モデルを再度解決するため、返された記述情報を編集しても、操作を別のエンドポイントに向けることはできません。

実装済みの画像APIはopenrouter-imagesです。分類APIはtypesafe-system-one、cloudflare-workers-ai-system-one、llama-cpp-classify、openai-decisionsです。ローカルのリクエスト／結果チェックは、あらゆる外部デプロイやアカウントの動作を検証済みであることを意味しません。

たとえば、Codemode内では次のように使います。

const candidates = await models.getAvailableOfType("image");
if (!candidates.length) throw new Error("Configure an image model first");
const result = await models.generateImages(candidates[0], {
  input: [{ type: "text", text: "A landscape watercolor of a quiet lake" }],
});
if (result.stopReason !== "stop") throw new Error(result.errorMessage);
for (const block of result.output) {
  if (block.type === "image") image(block);
}

generateImagesはテキストと、任意のbase64形式の参照画像ブロックを受け付けます。classifyはstate、questions、およびモデルが対応する任意の画像を受け付けます。質問の型はchoice、score、boolです。ネイティブの失敗は、型付きのerror/aborted結果として保持されます。出力を使う前にstopReasonを確認してください。これらのヘルパーは、汎用のmodels.chat()インターフェースを追加するものではありません。

分類のコンテキストには、オブジェクトのstateと、空ではないquestionsオブジェクトが必要です。各質問にはtype、instructions、criteriaを指定します。

質問の型	criteriaの形式
choice	ラベルを文字列の意味に対応付ける、空ではないオブジェクト
score	最低から最高の順に並んだ、文字列の説明による空ではない配列
bool	trueとfalseの意味を持つオブジェクト

任意のimagesには{ type: "image", data: "<base64>", mimeType: "image/png" }形式のブロックを使い、画像に対応する分類モデルが必要です。分類の出力はanswers、画像の出力はoutputに入ります。バックエンドが利用量を提供する場合は、それも含まれます。

製品の画像生成ツールは別の経路です。現在はOpenAI Responsesを使い、会話の添付ファイルとして永続化します。Dashboardのこのルートを設定しても、openrouter-imagesや分類の項目は設定されません。

再試行、フォールバック、仮想ルーティング

これらの仕組みは、担当する範囲が異なります。

仕組み	制御する内容
Sessionの自動再試行	再試行可能なアシスタントエラーを再実行する。既定は有効、再試行は3回。待機時間は2,000 msから指数的に増え、上限は60,000 ms
プロバイダーSDKの再試行	retry.providerに従い、条件に合う初期のトランスポート／HTTP失敗を再試行する。すでにストリーミングされたレスポンス本文は再実行しない
設定済みのフォールバック	エラーポリシーが許可する場合、順序に従って互換性のあるプロバイダー／モデルを試す
仮想モデルのコールバック	登録済みの仮想モデル選択を、カタログ上の実体モデルと実際の推論レベルに解決する

最初のリクエストは、Sessionの再試行回数に含みません。課金やアカウント上限のエラーは、通常の一時的エラーの再試行対象ではありません。コンテキストの超過時は、この再試行経路ではなくコンテキスト復旧を行います。キャンセルすると、再試行の待機が終了します。retry.enabled: falseはSessionの自動再試行を無効にしますが、各プロバイダーのSDK動作や設定済みフォールバックをすべて無効にするものではありません。

高度なProfile設定では、次の正確なcamelCaseキーを使います。

retry:
  enabled: true
  maxRetries: 3
  baseDelayMs: 2000
  maxAgentDelayMs: 60000
  provider:
    maxRetries: 0
    maxRetryDelayMs: 60000
httpIdleTimeoutMs: 300000

retry.provider.timeoutMsは、省略可能なプロバイダーリクエストのタイムアウト設定です。httpIdleTimeoutMsの既定値は300,000 msで、0またはdisabledにするとアイドルタイマーを無効にします。メディアルートには独自の制限があります。Sessionの再試行、SDKの試行、フォールバックの試行、Codexのネイティブなトランスポート復旧は別々の仕組みです。そのため、一つの設定がリクエスト総数や総所要時間の上限になるわけではありません。

仮想モデルは、内部のpi-virtual登録／コールバックインターフェースを使います。六種類目のリモート推論プロトコルではなく、v0.1.107には、YAMLによる仮想ルーター宣言、CLIウィザード、Dashboardのルーターエディターはありません。登録済みのコールバックはuser/continuation/retry/directのコンテキストを受け取り、ブランチのルート状態を保持できますが、利用可能な認証情報を持つ、カタログ上の実体モデルを返す必要があります。未登録のモデルや、再帰的に別の仮想モデルへルーティングすることはできません。フォールバック一覧を設定するだけで、このようなコールバックが登録されることはありません。

日常の設定は、モデルの設定とDashboardのモデルを参照してください。