Rerankモデル cl-nagoya/ruri-v3-reranker-310m を動かすために、行った「6つの対応とトラブルシューティング」をまとめました。
1. Xinference (推論サーバー) のDocker環境構築
Difyの環境に影響を与えずにローカルでモデルを動かすため、docker-compose.override.yaml を作成し、Difyと同じネットワーク上に推論サーバーである「Xinference」のコンテナを追加・起動しました。
/Users/dify/docker/ フォルダの中に、新しく docker-compose.override.yaml を作成して以下のように記述しました。
services:
xinference:
image: xprobe/xinference:latest
container_name: xinference
ports:
- "9997:9997"
volumes:
- ./volumes/xinference:/root/.xinference
command: xinference-local -H 0.0.0.0
restart: always
2. Xinference V2フォーマットへの対応
Xinferenceの最新版ではモデル設定ファイルの書き方が「V2形式」に変更されていました。旧形式ではエラーで読み込まれなかったため、HuggingFaceの情報を正確に指定したV2フォーマットのJSON設定を作成し直しました。
{
"model_name": "ruri-v3-reranker",
"model_type": "rerank",
"model_id": "cl-nagoya/ruri-v3-reranker-310m",
"language": ["ja"]
}
{
"version": 2,
"model_name": "ruri-v3-reranker",
"type": "normal",
"language": [
"ja"
],
"max_tokens": 8192,
"model_specs": [
{
"model_format": "pytorch",
"model_src": {
"huggingface": {
"model_id": "cl-nagoya/ruri-v3-reranker-310m",
"quantizations": [
"none"
]
}
}
}
]
}
3. カスタムモデル制限の回避（標準搭載モデル化）
カスタムモデル（自作モデル）の追加機能が、Xinference側の不具合や仕様で正しくUIから認識されない問題が発生しました。 これを突破するため、Xinferenceの**「標準搭載されているモデルのシステムリスト (rerank_models.json)」に直接 ruri-v3-reranker を書き込み**、最初からXinference内蔵モデルであるかのように強制認識させる対応を行いました。
-
内蔵モデル定義ファイルの特定 Xinferenceのシステム内部（Dockerコンテナの中）を検索し、元から表示されている bge-reranker-v2-m3 などの公式モデルが定義されているシステムファイル本体（rerank_models.json）を見つけ出しました。
-
システムファイルへの直接追記 コンテナの中からその rerank_models.json を一旦取り出し、ファイルの末尾に ruri-v3-reranker のV2フォーマットのJSONブロックをごっそり書き加えました。
-
コンテナ内ファイルの強制上書き 書き換えたファイルを、以下のDockerコマンドを使ってコンテナ内の本来のシステムパス（/root/.xinference/model/v2/builtin/rerank/rerank_models.json）へ上書きコピーしました。
docker cp 編集したファイル xinference:/root/.xinference/model/v2/builtin/rerank/rerank_models.json
- サーバーの再起動 コンテナを再起動させると、Xinferenceは起動時にこのファイルを読み込みます。システムは ruri-v3-reranker を「公式サポートされている標準モデルの1つ」として認識し、無事にUIのリストに表示されるようになりました。
4. 仮想環境構築エラーの回避
モデルの起動（Deploy）時に、Xinferenceは通常、独立したPython仮想環境を自動で作成します。しかし、今回の環境では依存パッケージの衝突で環境構築がクラッシュしました。 これを防ぐため、設定ファイルから virtualenv の項目を削除し、「仮想環境を作らずにコンテナの大元のPython環境を直接使う」 ように設定を書き換えました。
起きていたエラー（依存ライブラリの衝突）
Xinferenceは、新しいモデルを起動（Deploy）する際、他のモデルとシステム環境が混ざらないように「モデル専用の隔離されたPython仮想環境（VirtualEnv）」を毎回新しく自動で作成しようとします。
裏側では uv pip install というコマンドが走っていたのですが、Xinferenceのシステム自体が要求するライブラリ（peft<=0.17.1 など）と、ruriモデルを動かすのに必要なライブラリ（sentence-transformers 等）のバージョン条件が激しく衝突してしまい、環境の構築途中でクラッシュして「Server error 500」を返していました
実行した対応（仮想環境の強制無効化）
「専用の仮想環境を作ろうとするから衝突して失敗する」のであれば、「仮想環境を作る機能そのものをオフにしてしまえばいい」と考えました。
具体的には以下の対応を行いました。
-
設定ファイルからの記述削除 先ほど「システム標準モデルのリスト（rerank_models.json）を書き換えた」とご説明しましたが、実はそのファイルの中には「仮想環境構築時にどのパッケージをインストールするか」を指定する virtualenv というブロックが存在します。
-
自動構築処理のバイパス（スキップ） Pythonスクリプトを書いてコンテナ内のJSONファイルを再度編集し、ruri-v3-reranker の設定項目の中から "virtualenv": { ... } のブロックを丸ごと削除して上書き保存しました。
-
グローバル環境の利用へ切り替え このブロックを消し去ったことで、Xinferenceは「このモデルには専用の仮想環境や追加のインストールは不要なんだな」と判断するようになります。結果として、構築時に発生していた依存関係の衝突エラーを完全にスキップし、Dockerコンテナの大元（グローバル）のPython環境をそのまま使ってモデルを動かすように動作を変更させることができました。
※ただし、この対応を行うと「大元のPython環境」を使うことになるため、今度は大元の環境に sentence-transformers などの必須ライブラリが存在しないという別のエラーが発生しました。それが次のステップの「内部ライブラリの強制アップグレード（コンテナの大元環境への直接インストール）」へと繋がっていきます。
5. 内部ライブラリの強制アップグレード
仮想環境を使わないようにした結果、大元の環境に sentence-transformers 等の必須ライブラリが不足しており、また peft と transformers のバージョンが古くて互換性エラーが発生しました。 Xinferenceのコンテナ内で直接以下のコマンドを実行し、すべての関連ライブラリを強制的に最新版にアップグレードしました。
pip install -U peft transformers sentence-transformers einops
具体的には以下のような流れで対応しました。
-
不足していたライブラリの直接インストール
仮想環境の自動構築をスキップしたため、当然ながら大元の環境には ruri モデルを動かすための必須ライブラリが存在せず、Failed to import module 'sentence-transformers' というエラーが発生しました。 そのため、まずはコンテナの大元の環境に手動で必須ライブラリをインストールしました。 -
古いライブラリによる互換性エラー（新たな壁）
必須ライブラリを入れたところ、今度は cannot import name 'HybridCache' from 'transformers' という深刻なエラーが発生しました。 原因を調査すると、新しく入れたライブラリが最新版の transformers (v5.14.1) を連れてきた一方で、Xinferenceの大元環境に最初から入っていた peft (v0.17.1) が古すぎたため、新旧のバージョンが噛み合わずにプログラムがクラッシュしていました。 -
まとめて強制アップグレード（解決策）
この複雑に絡まったバージョンの衝突を解決するため、コンテナ内で以下のコマンドを実行し、**関係する全てのコアライブラリを一斉に最新版へと強制アップグレード（および新規インストール）**しました。
▼ アップグレード / インストールした具体的なライブラリ名：
-
sentence-transformers
ruri-v3-reranker などのモデルを読み込み、文章の類似度計算（リランク）を行うための最重要ライブラリです。新規でインストールされました。 -
transformers
AIモデルを動かすための基盤ライブラリ（Hugging Face製）です。古いバージョンから、最新の v5.14.1 へとアップグレードされました。 -
peft
モデルの微調整や効率的な推論に使われるライブラリです。古い v0.17.1 では新しい transformers と通信できなかったため、互換性のある最新の v0.19.1 へとアップグレードしました。 -
einops
AIモデル内部の複雑な行列計算を行うためのライブラリです。モデルによっては必須となるため、念のため最新版を一緒に追加・アップグレードしました。
6. API認証（Credentials）の無効化対応
DifyからXinferenceへ接続しようとした際、Could not validate credentials という認証エラーが発生しました。 最近のXinferenceのアップデートで、APIへの外部アクセス時に認証（ID/パスワード）がデフォルトで要求される仕様になったためです。 上記までの修正（コンテナ内の直接編集）を消さないように、一度 現在のコンテナの状態をイメージとして保存（Docker Commit）した上で、docker-compose.override.yaml に以下の環境変数を追加してコンテナを再構築しました。
- XINFERENCE_AUTH_ENABLE=false
- XINFERENCE_AUTH_ADVANCED=false
これにより、Difyから認証なしでAPIを叩けるようになりました。
services:
xinference:
- image: xprobe/xinference:latest
+ image: xinference-ruri-fixed
container_name: xinference
ports:
- "9997:9997"
+ environment:
+ - XINFERENCE_AUTH_ENABLE=false
+ - XINFERENCE_AUTH_ADVANCED=false
volumes:
- ./volumes/xinference:/root/.xinference
command: xinference-local -H 0.0.0.0
restart: always
TIP
Difyへの登録について 今後Dify側でこのRerankモデルを使う際は、以下の設定を入力。
- Model Type: Rerank
- Model Name: ruri-v3-reranker
- Server URL: http://xinference:9997
- Model UID: ruri-v3-reranker
:)