LangChain と阿里百炼の統合

LangChain は現在最も主流の大規模モデルアプリケーション開発フレームワークであり、統一されたコンポーネントインターフェースを通じて、開発者がプロンプト、モデル、ツールチェーン、エージェントアプリケーションを迅速に構築するのを支援します。

阿里云百炼（DashScope）は阿里云の大規模モデルサービスプラットフォームであり、通義千問（qwen）シリーズのチャットモデル、テキスト埋め込みモデル、再ランク付けモデルを提供しています。

この記事では、百炼モデルを LangChain に接続する方法を説明し、チャットモデル、テキスト埋め込みモデル、再ランク付けモデルの3つのカテゴリを網羅し、Python、JavaScript、Java の3言語の完全な例を示します。

事前準備

阿里云百炼モデルサービスを有効化し、API-KEY を取得する必要があります。

まず、阿里云のメインアカウントを使用して百炼モデルサービスプラットフォームにアクセスできます：https://bailian.console.aliyun.com/次に、右上隅のログインをクリックし、ログインが成功したら右上隅の歯車⚙️アイコンをクリックして API key を選択し、API key をコピーします。ない場合は API key を作成することもできます：

実際に作業を始める前に、2つの重要な概念を理解しましょう：LangChain の「モデル接続クラス」と、百炼の「2つの接続モード」です。

モデル接続クラス

LangChain は、異なるベンダーのモデルを統一された「接続クラス」にカプセル化します。

アプリケーションコードは統一インターフェースに対してプログラミングされ、ベンダーを切り替える際は接続クラスとパラメータを変更するだけで、ビジネスロジックはほとんど変更する必要がありません。

チャットモデルを例にとると、Python 側には ChatOpenAI と ChatTongyi という2つの接続クラスがあり、それぞれ百炼の OpenAI 互換モードと DashScope ネイティブモードに対応しています。

2つの接続モード

百炼は2セットの接続プロトコルを提供しており、異なるプロトコルを選択すると、異なる LangChain 接続クラスに対応します。

OpenAI 互換モード：インターフェースプロトコルが OpenAI と一致しているため、OpenAI プロトコルをサポートするフレームワークはすべて直接接続でき、接続コストが最も低くなります。

DashScope ネイティブモード：百炼独自の DashScope プロトコルを使用し、デプロイ後のカスタムモデルを含む百炼のすべてのテキスト生成モデルを呼び出すことができます。

全体的な接続アーキテクチャは次の図のとおりです：

「OpenAI 互換インターフェース」とは、ベンダーの HTTP インターフェースプロトコルが OpenAI と一致していることを指します。

プロトコルが互換性があれば、OpenAI 向けに書かれたコードやツールはすべて直接再利用でき、インターフェースアドレスを修正するだけで済みます。

環境変数の設定

すべての言語と接続方式は、環境変数を統一的に使用しますDASHSCOPE_API_KEYキーを保存します。

Linux / macOS ではターミナルでエクスポート：

export DASHSCOPE_API_KEY="sk-你的百炼APIKey"

Windows（CMD）での設定方法：

set DASHSCOPE_API_KEY=sk-你的百炼APIKey

エクスポートコマンドをシェル設定ファイル（例：~/.bashrc、~/.zshrc）に書き込むことをお勧めします。ターミナルを開くたびに再設定する必要がなくなります。

.env ファイルによる設定（推奨）

より推奨される方法は、キーをプロジェクトのルートディレクトリの .env ファイルに書き込み、python-dotenv と組み合わせて環境変数に自動的にロードすることです。

キーとコードを分離し、.gitignore と組み合わせることで誤ったコミットを防ぎ、複数人での共同作業時にもそれぞれが管理しやすくなります。

プロジェクトのルートディレクトリに .env ファイルを作成します：

# 文件路径：项目根目录/.env
DASHSCOPE_API_KEY=sk-你的百炼APIKey

たとえば、私たちがテストするプロジェクトサンプル-langchain-testの下に作成.envファイルに設定を追加します：

python-dotenv をインストール：

pip install python-dotenv

Python コードの先頭で .env ファイルをロード：

ロード後、コード内の os.getenv("DASHSCOPE_API_KEY") でキーを読み取ることができ、手動の export と同じ効果があります。

「チャットモデル」のセクションの例で、このロード方法をすでに示しました。

.env は機密ファイルです。.gitignore に追加（.env と1行記述）して、キーがバージョン管理リポジトリにコミットされないようにしてください。

サンプル内のキーを実際のキーに置き換え、他人に共有しないでください。

2つの接続方式の比較

まず比較表を見て、必要に応じて接続方式を選択してください。

2つのモードは同じドメイン dashscope.aliyuncs.com を使用しますが、違いはパスにあります：OpenAI 互換モードのパスは /compatible-mode/v1 で、DashScope ネイティブモードのパスは SDK に組み込まれています。

チャットモデル（Chat Model）

チャットモデルは最も一般的に使用されるモデルの一種で、マルチターン対話、Q&A、コンテンツ生成などのタスクに使用されます。

以下では言語ごとに接続方式を説明します。サンプルモデルは統一して qwen-plus を使用しますが、必要に応じて変更できます。

Python：OpenAI 互換方式

langchain_openai パッケージの ChatOpenAI 接続クラスを使用して、百炼を OpenAI サービスとして呼び出します。

まず依存関係をインストール：

pip install langchain_openai

サンプルコード：

出力結果（一部のフィールド省略）：

{
  "content": "我是通义千问，由阿里云开发的大语言模型，可以回答你的问题、协助创作、提供建议等。",
  "usage": { "prompt_tokens": 12, "completion_tokens": 28, "total_tokens": 40 }
}

呼び出しが成功すると AIMessage オブジェクトが返され、model_dump_json() で JSON にシリアライズして、完全なレスポンスを確認できます。

Python：DashScope ネイティブ方式

langchain-community パッケージの ChatTongyi アクセスクラスを使用し、DashScope ネイティブプロトコルでストリーミング出力に対応します。

ChatTongyi は langchain-community コミュニティパッケージに由来し、このパッケージと dashscope はメンテナンスを終了しています。

新規プロジェクトでは、OpenAI 互換方式の ChatOpenAI による接続を優先的に使用することをお勧めします。DashScope のネイティブ機能（モデルのデプロイなど）が必要な場合にのみ、この方式を検討してください。

まず依存関係をインストールします：

pip install langchain-community dashscope

サンプルコード：

出力結果：

chat resp: 你好
chat resp: ！我是通义千问，有什么可以帮您的吗？

ストリーミング出力により、モデルは生成と同時に内容を段階的に返すため、タイプライター効果が必要なチャットインターフェースに適しています。

テキスト埋め込みモデル（Embedding Model）

埋め込みモデルはテキストを意味ベクトルに変換し、RAG（検索拡張生成）やセマンティック検索などのアプリケーションの基盤となります。

モデル選定

百錬は複数バージョンの埋め込みモデルを提供しており、MTEB と CMTEB の2つの評価指標で効果を比較できます。数値が大きいほど優れています。

text-embedding-v3 と text-embedding-v4 は LangChain から呼び出す際にベクトル次元を指定できず、デフォルトで 1024 次元のベクトルを出力します。

バージョンが高いほど効果が良いため、v4 を優先的に選択してください。

Python の例

百錬の埋め込みインターフェースは OpenAI インターフェース仕様と互換性があり、langchain-openai パッケージの OpenAIEmbeddings アクセスクラスを直接使用し、base_url を百錬の互換エンドポイントに指定するだけで済みます。

メンテナンスが終了した langchain-community と dashscope の2つのパッケージをインストールする必要はありません。

まず依存関係をインストールします：

pip install langchain-openai

OpenAIEmbeddings には3つの重要なパラメータが必要です：model（埋め込みモデル名）、api_key（百錬の API キー）、base_url（百錬の OpenAI 互換エンドポイント）。

base_url は https://dashscope.aliyuncs.com/compatible-mode/v1 に固定されており、チャットモデルの互換エンドポイントと同じです。

サンプルコード：

出力結果：

文本向量长度：1024
文本向量数量：5 ，文本向量长度：1024

embed_query はユーザークエリをベクトル化するために使用し、embed_documents は候補ドキュメントを一括でベクトル化するために使用します。両者の出力ベクトル次元が一致して初めて類似度を計算できます。

再ランク付けモデル（Reranker Model）

再ランキングモデルは検索結果に対して2回目のスコアリングとソートを行い、RAG アプリケーションの回答品質を大幅に向上させることができます。

モデルパラメータ

百錬は以下の再ランキングモデルを提供しています。言語、コスト、シナリオに応じて選択してください：

Python の例

langchain-community パッケージの DashScopeRerank アクセスクラスを使用します。

このサンプルは langchain-community コミュニティパッケージの DashScopeRerank を使用しています。

langchain-community と dashscope はメンテナンスを終了しているため、新規プロジェクトでは百錬公式が提供する代替接続方式を確認してください。

まず依存関係をインストールします：

pip install langchain-community dashscope

サンプルコード：

rerank メソッドは query に基づいて候補ドキュメントを再スコアリングしてソートし、top_n で返却件数を指定します。RAG 検索後の精密ランキング段階でよく使用されます。

JavaScript と Java の接続

JavaScript：OpenAI 互換方式

Node.js 側では @langchain/openai パッケージの ChatOpenAI アクセスクラスを使用します。

まず依存関係をインストールします：

npm install @langchain/openai @langchain/core

サンプルコード：

出力結果：

---------------------------
J'adore la programmation.

JavaScript：DashScope ネイティブ方式

@langchain/community パッケージの ChatAlibabaTongyi アクセスクラスを使用します。

まず依存関係をインストールします：

サンプルコード：

Java：OpenAI 互換方式（LangChain4j）

Java エコシステムでは LangChain4j フレームワークを使用し、langchain4j-open-ai モジュールを介して百錬に接続します。

LangChain4j 1.0.0-beta3 は Java 17 以降が必要です。

Java 11 でコンパイルすると Unsupported class file major version 61 エラーが発生します。JDK をアップグレードすれば解決できます。

pom.xml に依存関係を追加します：

<!-- 文件路径：pom.xml -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.0.0-beta3</version>
</dependency>

サンプルコード：

Java：DashScope ネイティブ方式（LangChain4j）

langchain4j-community-dashscope モジュールを使用し、通常呼び出しとストリーミング呼び出しをサポートします。

pom.xml に依存関係を追加します：

<!-- 文件路径：pom.xml -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-dashscope</artifactId>
    <version>1.0.0-beta3</version>
</dependency>

サンプルコード（通常呼び出しとストリーミング呼び出し）：

LangChain4j は Spring Boot Starter も提供しており、手動でモデルオブジェクトを構築する必要はなく、application.properties で設定するだけです。

DashScope ネイティブ方式の Starter の設定項目は同名で、プレフィックスを langchain4j.community.dashscope.chat-model に変更するだけでよく、base-url の設定は不要です。

注意事項 / よくある質問

導入中に発生した問題は、以下のリストと照合して迅速に特定できます。

Java のバージョン要件

LangChain4j 1.0.0-beta3 は Java 17 以降が必要です。

Java 11 でコンパイルすると Unsupported class file major version 61 エラーが発生します。JDK をアップグレードすれば解決できます。

OpenAI 互換モードは一部のモデルのみをサポート

OpenAI互換インターフェースは百炼の一部モデルのみをサポートします。完全なリストは公式ドキュメントを参照してください。

呼び出すモデルがサポート範囲にない場合は、DashScope ネイティブモードに切り替えてください。

埋め込みベクトルのデフォルト次元

text-embedding-v3 / v4 を LangChain 経由で呼び出すと、デフォルトで 1024 次元のベクトルが出力され、次元を手動で指定することはできません。

データベースにテーブルを作成する際は、1024 次元のベクトルフィールドを確保してください。

API Key の安全性

APIキーをコードにハードコードせず、DASHSCOPE_API_KEY 環境変数から一括で注入してください。

本番環境では、Alibaba Cloud のキー管理サービスと併用することをお勧めします。

参考リンク

以下の公式ドキュメントで関連する詳細を詳しく確認できます：