モデル間でルーティングする¶

ADKでサポートTypeScript v1.0.0試験運用

試験運用

モデルルーティングは試験運用の機能であり、今後のリリースで変更される可能性があります。フィードバックをお待ちしています。

LlmAgent はデフォルトで単一のモデルを使用します。リクエストごとに異なるモデルから動的に選択する必要がある場合は、どのモデルを使うかを選ぶルーティング関数を定義できます。RoutedLlm はこの機能を提供し、エラー時のモデルフォールバック、モデル間の A/B テスト、入力の複雑さに基づく自動ルーティングを可能にします。選択されたモデルが出力を生成する前に失敗した場合、ルーティング関数はエラーコンテキスト付きで再度呼び出され、別のモデルを選択できます。

RoutedLlm を LlmAgent の model パラメータとして渡します。ルートごとにモデルだけが変わる場合は RoutedLlm を使用してください。指示、ツール、またはサブエージェントも切り替える必要がある場合は、代わりに RoutedAgent を使用します。

ルーティングの仕組み¶

LlmRouter 関数は、利用可能なモデルのマップと現在の LlmRequest を受け取り、使用するモデルのキーを返します。

TypeScript

type LlmRouter = (
  models: Readonly<Record<string, BaseLlm>>,
  request: LlmRequest,
  errorContext?: { failedKeys: ReadonlySet<string>; lastError: unknown },
) => Promise<string | undefined> | string | undefined;

models パラメータには、明示的なキーを持つ Record<string, BaseLlm>、または BaseLlm インスタンスの配列を渡せます。配列を渡した場合は、各モデルの名前がキーとして使用されます。

フェイルオーバーは RoutedAgent と同じルールに従います。選択されたモデルがレスポンスを 1 つも yield する前に失敗した場合にのみ、ルーターは errorContext 付きで再呼び出しされます。yield 後のエラーは再試行されず、そのまま伝播します。ルーターは undefined を返して再試行を停止し、最後のエラーを伝播できます。

ライブ接続: RoutedLlm.connect() は接続時にモデルを選択します。ライブ接続が確立された後は、ストリームの途中でモデルを切り替えることはできません。

基本的な使用方法¶

次の例では、まずプライマリモデルを試し、プライマリモデルが失敗した場合にセカンダリモデルへフォールバックする RoutedLlm を作成します。ルーターは失敗したモデルを再選択しないように errorContext.failedKeys を確認します。

TypeScript

import {
  BaseLlm,
  Gemini,
  LlmRequest,
  LlmAgent,
  RoutedLlm,
  InMemoryRunner,
} from '@google/adk';

const primaryModel = new Gemini({ model: 'gemini-flash-latest' });
const fallbackModel = new Gemini({ model: 'gemini-pro-latest' });

const router = (
  models: Readonly<Record<string, BaseLlm>>,
  request: LlmRequest,
  // errorContext is provided when a previously selected model fails
  errorContext?: { failedKeys: ReadonlySet<string>; lastError: unknown },
) => {
  if (!errorContext) {
    return 'primary'; // Try primary first
  }
  if (errorContext.failedKeys.has('primary')) {
    return 'fallback'; // Fall back if primary failed
  }
  return undefined; // No more options, propagate the error
};

const routedLlm = new RoutedLlm({
  models: { primary: primaryModel, fallback: fallbackModel },
  router,
});

// Use RoutedLlm as the model for an LlmAgent
const agent = new LlmAgent({
  name: 'my_agent',
  model: routedLlm,
  instruction: 'You are a helpful assistant.',
});

const runner = new InMemoryRunner({ agent, appName: 'my_app' });

const session = await runner.sessionService.createSession({
  appName: 'my_app',
  userId: 'user_1',
});

const run = runner.runAsync({
  userId: 'user_1',
  sessionId: session.id,
  newMessage: { role: 'user', parts: [{ text: 'Hello!' }] },
});

for await (const event of run) {
  if (event.content?.parts?.[0]?.text) {
    console.log(event.content.parts[0].text);
  }
}