サインインブリーフィングを予約

第 2.14 章

AIプロバイダーとモデル

人工知能(AI)Provider Router が組織独自のキープールからモデルを選択する方法、およびスクリプトやAIツールが外部から Nexus にアクセスする方法について説明します。

このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

読了時間 16 分

Harrow Port Authorityは2つのインストール環境を運用しています。エアギャップされた運用ネットワーク上の環境(第2.10章「エアギャップ・インストール」)には、ホスト型プロバイダーが一切ありません。本章で追う、接続された社内インストール環境では、ほとんどの質問に対し、港の自社サーバールームにある2台のグラフィックス処理装置(GPU)ノード上で動作するモデルが回答します。ローカルモデルがビジー状態のときは、Harrowが費用を負担するGoogle Geminiのキーがオーバーフローを引き受け、Aoife Brennanは組織の人工知能(AI)トラフィックをEU内にロックしています。Harrowでは、サービスやプラグインの内部でモデルを設定した人は誰もいません。Harrowが所有するものを1つのコンポーネントに伝え、そのコンポーネントがすべての呼び出しを決定します。

本章では、第1部やコンソールで「AIスイッチボード」と呼ばれているそのコンポーネント「AI Provider Router」と、それが利用するキーのプールについて説明します。最後には、スクリプトやAIツールが外部からNexusに到達する方法として、スクリプト用キー、REST(Representational State Transfer)アプリケーション・プログラミング・インターフェース(API)、およびModel Context Protocol(MCP)について説明します。

AI Provider Router

ルーターはゲートウェイであるnexus-gatewayの内部で動作します。これは組織のモデル認証情報を保持する唯一のサービスであり、各リクエストに対してどのプロバイダーとどのモデルが回答するかを最終的に決定します。Nexusの他のすべての部分は、このルーターに問い合わせます。ワークフローステップが希望を伝え、ルーターが決定します。

問い合わせができるサービスはごくわずかであり、それぞれのリストはチャートによって固定されています。

問い合わせ内容 問い合わせ可能なサービス
補完(/internal/ai/chatおよびそのストリーム) nexus-orchestrator, nexus-workflows, nexus-skills-engine
ツール呼び出しおよびその他の内部AIルート nexus-orchestrator, nexus-workflows
埋め込み(エンベディング)と再ランキング nexus-graphrag, nexus-skills-engine, nexus-workflows

各内部ルートは、呼び出し元の内部サービスキーと、上記のリストに対する呼び出し元のアイデンティティの2つを順番に確認します。キーのないリクエストはMISSING_SERVICE_KEY(401)で拒否され、誤ったキーはINVALID_SERVICE_KEY(403)で、呼び出し元が明示されていないリクエストはMISSING_CALLER_IDENTITY(403)で、リスト外の呼び出し元はUNAUTHORIZED_CALLER(403)で拒否されます。これらはいずれも一時的な障害ではないため、再試行されることはありません。

アプリやプラグインがそのリストに載ることは決してありません。プラグインは、登録するスキルに対して希望を宣言し、ワークフローエンジンであるUNOを介してディスパッチします。その後、オーケストレーターがプラグインに代わってルーターに問い合わせます。漏洩した1つのプラグインシークレットがそのプラグインとして動作できても、誰のモデル予算も消費できないのはこのためです。

左:「Assistant」、「Workflow step」、「Skill」の3つのボックスが縦に並び、それぞれから「UNO dispatch (nexus-orchestrator)」ボックスへ矢印が伸びています。「wishes: preferred provider, preferred model, capability profile」とラベル付けされた矢印が、右側の大きなボックス「AI Provider Router (nexus-gateway)」に入っています。ルーターのボックスの内部には、「Role」、「Organisation pool」、「Routing policy」の3つの小さなボックスが一列に並んでいます。ルーターからは、右側の「Local model (ai.localProvider.baseUrl)」、「Hosted provider key A」、「Hosted provider key B」へ3本の矢印が伸びています。ルーターの下には別のボックス「nexus-auth: the organisation's key pool (encrypted)」があり、「keys, resolved per call」とラベル付けされた破線の矢印がルーターに向かって上向きに伸びています。
リクエストがモデルに到達する仕組み。

組織のキープール

モデルキーは組織に帰属します。各組織は独自のプロバイダーアカウントを持ち込んで自らの請求を支払い、キーはnexus-auth内で暗号化されて組織のプールに保存されます。組織の背後に共有のプラットフォームキーは存在しないため、ある組織が別の組織の予算を消費することは決してありません。このルールの代償は明確です。プールにキーがない組織は、AIの回答を一切得られません。アシスタントはMODEL_NOT_CONNECTED(503)を表示し、誰がキーを接続できるかを伝えます。

以下の4つのプロバイダーのキーをプールに追加できます。

プロバイダーID 表示名
anthropic_api_key Anthropic
gemini Google Gemini
openrouter OpenRouter
scaleway Scaleway

独自のモデルサーバー

組織は、HarrowのGPUノード上のモデルのように、OpenAI互換APIを話す自社運用の任意のサーバーを使用することもできます。インストーラーはvaluesファイルでそれを指定します。

# harrow-values.yaml (Helm values): the AI part
ai:
  localProvider:
    baseUrl: "https://models.harrow.example/v1"
  installationHosts:
    - models.harrow.example
    - 10.40.20.0/24
networkPolicy:
  externalEgressCIDRs:
    - 10.40.20.0/24

ai.localProvider.baseUrlは、ゲートウェイのOpenAI互換アダプターを自社のサーバーに向けます。インストール環境では、プールのscalewayスロットがそのサーバーに到達するため、scaleway用に追加するキーは、自社のサーバーが要求するキーとなります。

ai.installationHostsには、リリースの独自のサービスドメインと3つの公開ホスト以外に、インストール環境内にあるホスト名を列挙します。各エントリは、ホスト名、.suffix、IPアドレス、またはIPv4クラスレス・ドメイン間ルーティング(CIDR)範囲です。ルーターはこのリストを使用して、サイト内に留まる呼び出しとサイト外に出る呼び出しを区別します。これは、「自社のハードウェア上のモデルを接続する」ページの「このサイトから外部にデータが出ることはありません」というチェックが報告する内容です。

ネットワークポリシーはルーターと同様に重要です。ネームスペースはデフォルトですべての送信(エグレス)を拒否するため、ゲートウェイがネームスペース外のモデルサーバーに到達できるのは、その範囲がnetworkPolicy.externalEgressCIDRsに含まれている場合のみです。ホスト型プロバイダーについても同様です。HarrowがGeminiキーに回答させたい場合、プロバイダーのアドレス範囲もそこにリストされていなければならず、そうでなければ呼び出しがクラスターから出ることはありません。ポリシーの詳細については、第2.16章「セキュリティとネットワーキング」で説明しています。

自社のハードウェア上のモデルを接続する
自社のハードウェア上のモデルを接続する
自社のハードウェア上のモデルの接続。このページには、サーバーが報告するモデル、各モデルが果たす役割が一覧表示され、サイトから外部にデータが出ないことが確認されます。

キーの追加と取り消し

組織のオーナーと管理者がそのプールを管理します。他のユーザーはキーを見ることも変更することもできず、それらのユーザーからのリクエストはAUTHORITY_EXCEEDEDで拒否されます。

コンソールでの操作

Enterpriseでは、プールはエンジンの下のAIスイッチボードで管理されます。Communityでは、同じキーが「設定」の「AIモデル」で管理されます。そのページは基本的なルーターであり、キーとローカルモデルのアドレスを追加し、どのモデルがどのジョブを実行するかを選択します。どちらも、各キーを設定したユーザーと日時(「Set by Aoife, 3 Sept」)、および••••7f2qのような最大で末尾4文字のマスクされたヒントによって表示します。キーを追加した後は、キー自体が再度表示されることは決してありません。

AIスイッチボード
AIスイッチボード
AIスイッチボードには、各プロバイダーが、誰がそのキーを設定したか、どのジョブを実行するかとともに一覧表示されます。1つのキーは失敗後に休止中であり、もう1つのキーはオフにされており、ページにはデータの送信先として許可されている場所が示されています。
AIモデル
AIモデル
Communityにおける基本ルーター:組織キー、組織の自社マシン上のローカルモデル、およびどのモデルがどのジョブを実行するか。

BFF API経由

コンソールのフロントエンド用バックエンド(BFF)は、プール用に3つのルートを提供します。個人のアクセストークンを使用してこれらを呼び出します。組織はトークンから取得され、リクエストから取得されることは決してありません。

GET  /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw

GETは、プール内のプロバイダー、それぞれが回答可能かどうか、ヒントによるすべてのキー、およびキーを追加できるプロバイダーを返します。キーの追加には、2つの必須フィールドと1つの任意フィールドを持つJSONボディが必要です。

{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }

キーは一度だけ送信されます。nexus-authがそれを暗号化してルーターに伝え、応答にはヒントのみが含まれます。応答は201であり、新しいキーのIDとその行(「Added. The Google Gemini key ••••7f2q is in the organisation's AI pool, and the AI Provider Router can route to it now.」)が含まれます。ラベルは最大100文字で、キーはスペースを含まない最大4,096文字の1つの文字列です。ボディ内のその他のフィールド、または組織や個人を指定するフィールドは拒否されます。

取り下げ(Withdrawing)には空のボディを使用します。ルーターはただちにそのキーへのルーティングを停止し、nexus-authは履歴が残るようにそれを取り下げ済みとしてリストに保持します。プール内のものが削除されることは決してありません。

拒否 HTTP 発生条件
VALIDATION_FAILED 400 {provider, api_key, label?}ではないボディ、不明なプロバイダー、または組織キーとして提供された個人のサブスクリプション
AUTHORITY_EXCEEDED 403 呼び出し元が組織のオーナーまたは管理者ではない
RECORD_NOT_FOUND 404 そのIDを持つキーが組織のプールに存在しない
TRANSITION_NOT_PERMITTED 409 キーはすでに取り下げられている
TENANT_NOT_A_PARAMETER 403 ボディまたはクエリで組織が指定された

キーの状態

プール内の各キーは6つの状態のいずれかにあります。使用中(in use)のキーのみがチャットに回答します。

状態 意味
in_use キーは回答します(有効期限がある場合はその日まで)。
resting 失敗後、ルーターが一定の時刻まで休止させました。その間、リクエストは次のキーに送られます。
exhausted プロバイダーでの上限を使い果たしました。
invalid プロバイダーがそれを受け付けなくなりました。
expired 有効期限が切れて失効しました。
withdrawn 管理者がそれを取り下げました。履歴としてリストに残ります。

失敗したキーは60秒間休止します。5回連続して失敗すると、ルーターはそれをオフにし、その割り当てを他のキーに移し、通知PROVIDER_KEY_SWITCHED_OFFを記録します。別のキーが回答できる間は、誰も拒否されません。

プロバイダーに使用中のキーがない場合、プールはその理由を示します(「No key in use: 1 withdrawn, 1 lapsed」)。プール内のどのプロバイダーにも使用中のキーがない場合、チャットはNO_PROVIDER_FOR_ROLE(422)と対処法(オーナーまたは管理者が組織キーを追加すること)とともに拒否されます。これは設定状態であり、誰かが修正するまで画面に表示され続けます。

ロール、ポリシー、および希望条件(wishes)

ルーターはロール(役割)単位で判断します。すべてのリクエストは、default、fast、reasoning、code、またはlong_contextの5つのいずれかに対するものです。また、各モデルはfrontier、standard、またはfastのティア(階層)に属しており、ロールが許す場合はより高いティアが優先されます。組織は、どのプロバイダーが各ロールを提供するか(ロール割り当て)、およびプロバイダーが失敗した際にフォールバックする順序(ルーティングポリシーのラダー)を決定します。管理者はAIスイッチボードで両方を設定します。また、nexus-authは、ai_provider:manageを保持する管理者キーに対して、/auth/org/<organisation-id>/settings/ai-provider/role-assignmentsおよび/auth/org/<organisation-id>/settings/ai-provider/routing-policyでそれらを提供します。

呼び出し元は希望を伝えることができます。スキル行には、優先プロバイダーと優先モデル、さらに機能プロファイルを含めることができます。ルーターはそれぞれを異なる方法で扱います。

  • 優先プロバイダーは、組織がそのプロバイダーを有効にしており、そのキーを持っている場合にのみ尊重されます。そうでない場合、ルーターは代替を使用します。
  • 優先モデルは、それがそのプロバイダーのカタログにあり、プロファイルに適合する場合に尊重されます。
  • 機能プロファイルはフィルターであり、選択を行うことは決してありません。最小コンテキストウィンドウ、ツール使用、ビジョン、埋め込み、ロングコンテキスト、またはデータレジデンシー(データ所在地)を要求できます。これを満たさないものはすべて対象外となります。

ルーターは固定された順序で選択します。可能な場合は希望を尊重し、次に同じプロバイダーの別のモデルを試し、次にロール割り当て、そしてカタログが適合するキーを持つ他のプロバイダーを試します。プロファイルが指定され、それに適合するカタログがない場合、リクエストはMODEL_CAPABILITY_UNAVAILABLE(422)で拒否されます。何も割り当てられておらず、一致するものがない場合は、NO_PROVIDER_FOR_ROLE(422)となります。最後の手段としてのデフォルトモデルは存在しません。設定していないロールは、何を設定すべきかを示すルーター自身の言葉とともに、明確に失敗します。

データレジデンシーは、代替によって回避することができない唯一の制約です。eu_onlyを持つプロファイルは、EUのプロバイダーによって提供されるか、拒否されます。Harrowは組織全体にこのロックを設定しており、スイッチボードは米国リージョンにある2つ目のホスト型プロバイダーをオフとして描画します。

スキルが動作するために特定の1つのモデルを必要とする場合、スキルはその正確なモデルを固定(ピン留め)することもできます。その場合でも、ルーターはそれに対して組織自身のキーを使用し、キーがなければ何も回答しません。呼び出し元が、組織が設定していないプロバイダーをNexusに使用させることは決してできません。

プロバイダーが選択された後のフェイルオーバーは別の問題です。429、5xx、またはネットワーク障害が発生すると、リクエストはラダーを下って次のプロバイダーに移動します。400、401、403、または404の場合はただちに停止します。認証情報やリクエストの形式はプロバイダー間で引き継がれず、再試行してもクォータを消費して同じ失敗に至るだけだからです。

誰かが質問する前にルーターが何を選択するかを確認するには、個人のトークンを使用してゲートウェイ上のGET /api/ai/routing-policy/effectiveを読み取ります。サインインしている組織に対するモデル、または該当するものがない場合はルーターの拒否理由を言葉で返し、モデルにはリクエストを一切送信しません。

ルーターの監視

すべてのページの下部にある数値ストリップには、使用中のモデル(「Model: local」)が表示されます。Enterpriseでは、「ライブAIスイッチボード」がルーターのトラフィックをリアルタイムで描画します。アシスタント、ジョブ、アプリからのリクエストがロールを通ってプロバイダーとキーに流れる様子や、60秒間の休止中のキーがグレーで、オフにされたキーが赤で描画され、ローカルモデルがビジー状態のときにホスト型プロバイダーへフォールバックする様子が示されます。フローの横には、プロバイダーごとの負荷、1秒あたりのリクエスト数、および待機時間がチャート表示されます。Tomásは、ルーティングポリシーを変更した後の最初の1週間はこの画面を開いたままにします。ロールの割り当てに誤りがあると、誰も意図していない場所にトラフィックが流れる様子が数分以内にそこに現れるからです。

Communityでは、「AIモデル」ページに「すべてのモデルをテスト」ボタンがあり、設定された各モデルをチェックして回答するかどうかをマークします。これは、誰かが新しいキーに依存する前に、それが機能することを証明する最も迅速な方法です。

ライブAIスイッチボード
ライブAIスイッチボード
稼働中のルーター。トラフィックはアシスタントとジョブからロールを通ってローカルモデルとホスト型キーに流れます。1つのキーは休止中、1つはオフにされており、金色のドットはローカルモデルがビジー状態の間のフォールバックを示しています。

エンベディング

検索とナレッジグラフはテキストをベクトルに変換します。デフォルトでは、インストール環境はクラスター内のプロセッサー上で動作する埋め込みモデルを使用してこれを行うため、埋め込みのためにテキストがサイト外に出ることはなく、組織はキーを必要としません。埋め込みにホスト型プロバイダーを使用することは組織が行う選択であり、その場合は同じプールと同じルールを通過します。

ルーターに埋め込みや再ランキングを要求できるサービスは、nexus-graphrag、nexus-skills-engine、およびnexus-workflowsの3つだけです。GraphRAGは、コンテンツの所有者である組織として、その組織の設定を使用して埋め込みを行い、独自のプロバイダーキーは保持しません。組織が埋め込みモデルを変更すると、nexus-workflowsがその組織のストアに対して再埋め込みジョブを実行します。

個人別の認証情報は個人のまま維持

一部の認証情報は1人の個人に帰属します。その個人のアカウントを通じてサインインするClaude Maxサブスクリプションが一般的な例です。このような認証情報が組織キーになることは決してありません。プールはそれをVALIDATION_FAILEDで拒否し、組織のキー一覧表に載ることは決してなく、他の人の画面に表示されることもありません。

また、モデルキーが他の場所に行くことも決してありません。外部データソースのキーを保持する「外部データキー」ページは、AIモデルキーのように見えるものをすべてAI_PROVIDER_KEYS_BELONG_TO_ORG_POOL(422)で拒否します。ファイルリーダーが、本来あるべきではないドキュメントや設定の内部でモデルキーを見つけた場合、CREDENTIALS_IN_WRONG_PLACEを記録し、管理者がそれらを削除して置き換えます。

スクリプト、REST、および MCP

Nexusには3つの公開ホストがあります。Harrowでは、コンソール用のconsole.harrow.example、ゲートウェイ用のapi.harrow.example、サインイン用のauth.harrow.exampleです。スクリプトとツールは2番目と3番目を使用します。

スクリプト用キー

スクリプトは、「設定」の「スクリプト用キー」で作成されたキーを使用してサインインします。各キーには、名前、適用範囲(たとえば「Start Drone yard count only」)、作成者、および終了日があります。組織はキーが持つことのできる最長有効期間をロックできます。シークレットはキーの作成時に一度だけ表示されます。Nexusは末尾の4文字しか保持しないため、スクリプトのシークレットストアにコピーしてください。キーは取り下げられるものであり、削除されることはありません。ただちに停止し、行ったすべての呼び出しとともにリストに残ります。ローテーションを行うと、キーに新しいシークレットが付与され、一度だけ表示されます。

各キーには専用のページがあり、1日あたりの呼び出し数、サービス別の呼び出し数、および時刻、アドレス、サービス、結果のアクティビティログが表示されます。キーの適用範囲外の呼び出しは拒否され、ログに表示されます。

nexus-authは、サインインしているユーザーに対してhttps://auth.harrow.example/api-keysで同じキーを提供します。作成と一覧表示、およびIDによる1つのキーの読み取り、変更、失効、またはローテーションが可能です。

1つのスクリプト用キー
1つのスクリプト用キー
1つのスクリプト用キー。このページには、キーの適用範囲、作成者、終了日、日別およびサービス別の呼び出し数、そしてすべての呼び出しの結果が表示されます。シークレットは末尾が…7QK2であり、二度と表示されません。

ゲートウェイ経由のREST

Authorization: Bearer <token-or-key>を使用してhttps://api.harrow.exampleにREST呼び出しを送信します。すべてのキーは組織に属している必要があります。組織に属していないキーは、nexus-authを通じてキーをチェックするすべてのサービスによってTOKEN_ORG_MISSING(403)で拒否されます。

頻繁に要求しすぎる呼び出し元には、RATE_LIMITED、Retry-Afterヘッダー、およびボディ内の制限値とウィンドウとともに429が返されます。指定された秒数だけ待機してください。Enterpriseでは、管理者が「設定」の「レート制限」で、キーごと、アプリごと、およびユニットごとに制限を設定します(第2.16章「セキュリティとネットワーキング」を参照)。

AIツール用のMCP

Model Context Protocolを話すAIツールはhttps://api.harrow.example/mcpに接続します。これらはhttps://auth.harrow.exampleにあるOAuth 2.1サーバー(OAuthは委任認可のためのオープンスタンダードです)を通じてサインインします。このサーバーはツール自体によるクライアント登録をサポートしているため、Claude CodeやCursorなどのツールは自身を登録し、ユーザーのブラウザーを開いてサインインします。その後、接続はその1人のユーザーに代わって、そのユーザーの権限のみを持って動作します。サインインしたユーザーは、コマンドラインツール用の既製の設定をhttps://auth.harrow.example/api/v1/mcp/cli-configから取得できます。

モデルを必要とするツール呼び出しは、他のすべてと同様に、ユーザーの組織の下でルーターを通過します。