LangChainの接続先をリクエスト単位で切り替える方法|LangSmith GatewayとChatXAIの設定

同じPythonサービスで、ある処理はLangSmith Gateway経由、別の処理は別の接続設定にしたい。そんな場面に向けて、LangChain core 1.8.1にlangsmith_gatewayが追加されました。公開は2026年11月15日14:57 UTC、日本時間では15日23:57です。続いて公開されたlangchain-xai 1.4.0ではChatXAIも共通のGateway設定を使えます。

複数のリクエストから選んだ経路だけが中央のゲートを通ってAIモデルへ向かう概念イラスト
リクエストごとの接続先切り替えを表した生成イラスト。実際の製品画面ではありません。

ポイントは、呼び出し時ではなく、モデルオブジェクトを作る時に接続先を決めることです。ここではxAIを例に、実際の送信前に接続先を確認する手順を紹介します。コードは公開された実装に基づく例であり、この記事のために有料APIへ実行した結果ではありません。

目次

何が変わった?環境変数との違い

LANGSMITH_GATEWAYはプロセス全体に関わる設定です。複数のリクエストが同時に動くWebサービスで、リクエストごとにこの環境変数を上書きする設計は避けたいところです。新しいコンテキストマネージャーは、現在のスレッドやasyncioのコンテキストにGateway設定を持たせ、その中で作成する対応モデルに適用します。

コンテキスト内では、指定したGatewayキーがモデル側のキーや環境変数より優先されます。接続先もGateway配下にそろいます。ただし、すでに同じGateway基底URL配下の明示的なURLは保持されます。単にAPIキーだけを差し替える機能とは捉えないほうが理解しやすいでしょう。

最初にそろえる条件

  • Python 3.11以上、4未満の環境と、検証用の仮想環境。
  • Gatewayを利用できるLangSmithワークスペースと、そのワークスペースのAPIキー。
  • gateway:invokeとworkspaces:readの権限。トレース送信専用キーは用途が異なります。
  • xAIの利用可能なモデルと、ワークスペースに保存したxAIのプロバイダーキー。

管理者はLangSmithで対象ワークスペースを選び、Settings → Integrations → Provider secretsからxAIキーを保存します。クライアントがGatewayへ渡すのはLangSmithキーで、GatewayがxAIへ接続するためのキーとは別です。Gatewayはベータ提供であり、利用権限、モデル制限、料金、地域の接続先は自分の契約と設定を確認してください。

1.バージョンを固定して検証する

まず検証環境で次を実行します。既存アプリでは依存関係のロックファイルも確認し、pip checkの衝突を解決してから進めます。

python -m pip install "langchain-core==1.8.1" "langchain-xai==1.4.0"
python -m pip check

今回のコンテキスト関数はlangchain_core.utils._gatewayというprivateモジュールにあります。将来の互換性が保証された公開APIとして扱わず、利用箇所を小さな関数にまとめ、更新時に再確認してください。

2.モデルの生成をwithで囲む

LANGSMITH_GATEWAY_API_KEYには許可されたLangSmithキー、XAI_MODELには自分の環境で使えるxAIのモデルIDを設定します。下の既定接続先は米国のGatewayです。他地域では公式の地域別接続先を確認し、APP_GATEWAY_BASE_URLへ基底URLを設定してください。これはこの例で使う独自の設定名で、LangChain標準の変数ではありません。

import os
from langchain_core.utils._gateway import langsmith_gateway
from langchain_xai import ChatXAI

gateway_base = os.environ.get(
    "APP_GATEWAY_BASE_URL", "https://gateway.smith.langchain.com"
).rstrip("/")

with langsmith_gateway(
    api_key=os.environ["LANGSMITH_GATEWAY_API_KEY"],
    base_url=gateway_base,
):
    model = ChatXAI(model=os.environ["XAI_MODEL"])

assert str(model.xai_api_base).rstrip("/") == f"{gateway_base}/xai/v1"
print(model.xai_api_base)

この部分はモデルを構築し、設定されたURLを検査します。キーそのものは表示しません。withを抜けても、作成したmodelはGatewayの接続設定を持ち続けます。既存モデルのinvoke()だけをwithで囲んでも、後から経路が切り替わるわけではありません。

3.短い送信でトレースを確認する

接続先を確認できたら、権限と利用料金を確認したうえで次のような短い入力を送ります。LangSmithのトレースでモデル、実行結果、ポリシー判定を確認し、単に返答が来たことだけで経路を判断しないようにします。

response = model.invoke("Reply with OK.")
print(response.content)

実際のサービスでは、認証済みリクエストからサーバー側で選んだ設定を使ってモデルを構築します。クライアントから届いた任意のGateway URLやキーをそのまま信用しないこと、別ワークスペース向けのモデルを共通キャッシュで再利用しないことも設計上の確認点です。withの終了は、作成済みオブジェクトのキー消去ではありません。

切り替わらないときの確認順

  1. importできない:実行中のPython環境とcoreのバージョンを確認します。
  2. 通常のxAI URLのまま:ChatXAIのバージョンと、モデル生成がwithの内側かを確認します。
  3. 認証や権限エラー:Gatewayに渡すLangSmithキーと、ワークスペース側のxAIキーを分けて確認します。キー保存時にはプロバイダーの有効性は検証されません。
  4. モデルやポリシーで拒否:モデルID、ワークスペース、許可モデル、上限をトレースと照合します。

同日のGroq、MistralAI、DeepSeek連携にもGateway対応が入りました。ただしクライアント側の対応だけで、すべての接続先やモデルの利用が保証されるわけではありません。まず公式に案内されているプロバイダーで小さく確認し、必要な経路だけに適用すると原因を切り分けやすくなります。

一次情報

この記事を書いた人

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows/Office(Teams・Excel)からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

コメント

コメントする

目次