> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/platform-development/onprem-model-services.md).
# オンプレミスのモデルサービス接続
プライベートクラウドとオンプレミス環境でのモデル接続方法：デプロイパッケージのローカルモデルカタログ（vLLM）、既存の OpenAI 互換モデルサービスへの接続（URL の /v1 ルールを含む）、独自のキーによるクラウドモデルの利用、独自の Embedding と Reranker に関する制限
MaiAgent の動作には、大規模言語モデル（LLM）、Embedding、Reranker の 3 種類のモデルが必要です。プライベートクラウドとオンプレミス環境では、3 種類の接続先からモデルを利用でき、組み合わせることもできます。例えば、LLM はクラウドを利用し、Embedding と Reranker はホスト上で実行できます。本ページは、モデルと GPU を計画するお客様の IT 部門および SI パートナー向けです。
{% hint style="info" %}
モデルはデプロイ時にデプロイ設定に指定します。本ページでは各接続方法のルールと制限を説明します。実際の設定項目は、デプロイパッケージに付属するインストールマニュアルに記載されています。入手については MaiAgent の担当者にお問い合わせください。
{% endhint %}
## 3 種類の接続方法
| 接続方法 | 説明 | 適したケース |
| ---------------- | ---------------------------------------------------------------- | --------------------------------------- |
| ホスト上で実行（ローカルモデル） | デプロイパッケージが GPU ホスト上で vLLM モデルサービスを起動します。モデルはパッケージのモデルカタログから選択します | データをデータセンター外に出せず、GPU を用意済みの場合 |
| 既存のモデルサービスに接続 | お客様がすでに OpenAI 互換モデルサービスをお持ちの場合、URL とキーを入力して接続します | 自社の推論プラットフォームやモデル中継サービスがある場合 |
| クラウドモデルサービスに接続 | お客様がクラウドプロバイダーのキーを用意し、MaiAgent がクラウド API を直接呼び出します | クラウドプロバイダーへのデータ送信を許容でき、クローズドモデルを利用したい場合 |
オフラインインストールでも、外部やクラウドのモデルサービスに接続できます。オフラインとは、インストール資材をインターネットからダウンロードしないことを指します。ファイアウォールでホストからモデルサービスへの接続を許可すれば利用できます（検証環境ではモデルサービスへの 443 ポートのみ許可しました）。
## ローカルモデルカタログ
デプロイパッケージのモデルカタログでは、以下のモデルを vLLM で実行できます。モデルの重みはデプロイパッケージに含まれません。オンラインインストールでは Hugging Face から自動的にダウンロードされ、オフラインインストールでは資材準備時にあわせてダウンロードする必要があります。
| モデル | 種類 | 特徴 | デフォルトの context |
| ---------------------------------- | --------- | ---------------------------------- | -------------- |
| gpt-oss-20b | LLM | ツール呼び出しに対応します | 128K |
| gpt-oss-120b | LLM | ツール呼び出しに対応します | 128K |
| Gemma 3 4B | LLM | 画像入力に対応します。**ツール呼び出しには対応しません** | 128K |
| Gemma 4 26B A4B | LLM | MoE アーキテクチャを採用し、ツール呼び出しと画像入力に対応します | 128K |
| Gemma 4 31B | LLM | ツール呼び出しと画像入力に対応します | 64K |
| Qwen3.6 27B（FP8） | LLM | ツール呼び出しに対応します | 32K |
| Qwen3-VL 32B | LLM | ツール呼び出しと画像入力に対応します（1 回あたり最大 5 枚） | 32K |
| jina-embeddings-v3 | Embedding | — | — |
| jina-reranker-v2-base-multilingual | Reranker | 多言語に対応します | — |
| bge-reranker-v2-m3 | Reranker | — | — |
* 各モデルの重みサイズと推奨 GPU は、[GPU ハードウェア計画](/tech/ja/platform-development/gpu.md)をご覧ください。Embedding と Reranker は、デフォルトでは GPU メモリの一部しか使用しないため、LLM と同じ GPU を共有できます。
* Agent でツールを使用する場合（Agent モード）は、ツール呼び出しに対応した LLM を選択してください。Gemma 3 4B は適していません。
* 表の context はデプロイテンプレートのデフォルト値で、GPU メモリに応じて設定されています。変更をご希望の場合は MaiAgent にご相談ください。
* カタログにないオープンウェイトモデルについては、MaiAgent にご相談ください。
## 既存の OpenAI 互換モデルサービスへの接続
各モデルは「外部サービス」に変更でき、URL とキーを指定できます。モデルサービスがキーを必要としない場合は、空欄のままデフォルト値を使用できます。
**URL のルール**（最もよくある設定ミスです）：
| モデルの種類 | URL に `/v1` を含めるか | 例 |
| --------- | ----------------- | -------------------------- |
| LLM | 含めます | `http://10.0.0.20:8001/v1` |
| Embedding | 含めます | `http://10.0.0.20:8001/v1` |
| Reranker | **含めません** | `http://10.0.0.20:8001` |
システムは Reranker の呼び出し時に `/v1/rerank` を自動で追加します。Reranker の URL を `…/v1` にすると、実際の呼び出し先が `…/v1/v1/rerank` となり、ナレッジベース検索と FAQ 検索がすべて失敗します。
その他のルール：
* **モデル名**：モデルサービス上のモデル名がデプロイ設定のデフォルト名と異なる場合は、デプロイ設定にモデルサービス上の名前を別途指定してください。
* **インストール後の設定変更**：モデルの URL やキーを変更した後は、モデル設定を再読み込みするだけで反映できます（検証では約 1 分）。再インストールは不要です。通常の再インストールでは読み込み済みのモデル設定がスキップされるため、変更は反映されません。
## クラウドモデルサービスへの接続（独自のキー）
プライベートクラウドとオンプレミス環境でクラウドモデルを呼び出す場合は、お客様自身のクラウドアカウントとキーを使用します。デプロイ設定には、OpenAI、Anthropic、Azure、AWS Bedrock、Cohere、Voyage、Gemini、Groq、Google Vertex AI の認証情報を指定できます。LLM、Embedding、Reranker のどれを利用できるかはプロバイダーによって異なります。比較は[クラウドモデル推論 API サービス](/tech/ja/platform-development/cloud-model-inference-api-service.md)をご覧ください。
* ホストから対象のクラウドサービスに接続できる必要があります。
* **AWS Bedrock**：キーに紐づく IAM ID にモデル呼び出し権限が必要です（ストリーミングとクロスリージョン inference profile を含みます。Claude シリーズは多くのリージョンで inference profile 経由でのみ呼び出せます）。Bedrock Guardrails や Bedrock の Reranker を使用する場合は、対応する権限も追加してください。IAM policy の例はデプロイパッケージに付属します。
* **Bedrock とバックエンドのバージョン**：`2026.Q3-08.24` から `2026.Q3-09.14` までのバックエンドでは Bedrock のキーを使用できません。`2026.Q3-09.15` 以降を使用してください。
* **AI Gateway**：オンプレミス環境の AI Gateway では、自社で構築したモデルのみ使用できます。[デプロイ形態と機能比較](/tech/ja/platform-development/onprem-deployment-types.md#feature-availability)をご覧ください。
### ハイブリッドクラウド：プラットフォームはローカル、モデルはクラウド
プラットフォームをお客様のデータセンターやクラウドに設置し、クラウドプロバイダーのモデルを使う場合は、上記の「クラウドモデルサービスへの接続」を利用します。別のデプロイ形態やコンポーネントはありません。次の順序で設定してください。
{% stepper %}
{% step %}
### モデルの種類ごとに接続先を決定
LLM、Embedding、Reranker それぞれについて、クラウドを使うかホスト上で実行するかを決めます。よくある組み合わせは、LLM をクラウドで利用し、Embedding と Reranker をホスト上で実行する構成です（これらのデータを内部ネットワークに留められ、大容量 GPU も不要です）。Embedding と Reranker に対応するクラウドプロバイダーは限られています。[クラウドモデル推論 API サービス](/tech/ja/platform-development/cloud-model-inference-api-service.md)をご覧ください。
{% endstep %}
{% step %}
### ホストからプロバイダーのエンドポイントへの接続を許可
ホストから各プロバイダーの API エンドポイントへ送信方向の接続（443 ポート）を許可するだけで利用できます。プロバイダーがホストへ接続することはありません。proxy の使用や許可リストのみの通信が必要な場合は、デプロイ前に MaiAgent にお知らせください。オフラインインストール環境でもこの方法で接続できます。本ページ冒頭の説明をご覧ください。
{% endstep %}
{% step %}
### デプロイ設定にキーを入力
プロバイダーの認証情報をデプロイ設定に入力します（AWS Bedrock では、モデル呼び出し権限を持つ IAM ID を事前に用意してください）。デプロイ設定にはキーが含まれるため、社内規定に従って保管してください。インストール後にキーやモデルを変更する場合は、モデル設定を再読み込みするだけで反映できます。再インストールは不要です。
{% endstep %}
{% step %}
### 検証
インストールまたは設定の再読み込み後に機能受入テストを実行し、会話とナレッジベース検索が正常に動作することを確認します。その後、管理画面の[モデル呼び出し権限](https://docs.maiagent.ai/org/model-access)で、組織からこれらのモデルが見えることを確認してください。
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
* **自動切り替えはありません**：クラウドモデルがタイムアウトしたり、プロバイダーで障害が発生したりしても、プラットフォームはホスト上のモデルに自動で切り替わりません。冗長化が必要な場合は、計画時に MaiAgent にご相談ください。
* **オンプレミスの計算リソースへの切り替え**：LLM と Reranker は、いつでもホスト上のモデルに変更できます。Embedding はナレッジベースで使用されると変更できません。Embedding を変更するには、別のナレッジベースを作成し、ドキュメントを再インポートする必要があります。
* **データフロー**：会話内容はクラウドプロバイダーへ送信され、処理されます。内部ネットワークの外へ出るのはモデル呼び出しのみです。会話履歴、ナレッジベースのファイル、ベクトルはホスト上に残ります。
{% endhint %}
## 独自の Embedding と Reranker に関する制限
| 制限 | 説明 |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Embedding サービスは 2 つのパラメーターを受け付ける必要があります | MaiAgent は `encoding_format: base64` と `truncate_prompt_tokens` を送信します。これらに対応しないサービスはリクエストを拒否し、ナレッジベースの全ファイルの解析が失敗します。接続前にモデルサービスの提供元に確認してください |
| Embedding の名前にコロン（`:`）が含まれます | 別途インデックス名を指定する必要があります。使用できるのは英小文字、数字、ハイフンのみです。指定しないと、ナレッジベースで検索インデックスを作成できません |
| Reranker の URL | `/v1` を付けません。上記の URL ルールをご覧ください |
| 対応するプロバイダーの種類 | Embedding：vLLM、Ollama、OpenAI、Cohere、Voyage、AWS Bedrock。Reranker：Cohere、Voyage、AWS Bedrock、FlagEmbedding、vLLM。Azure と Google Vertex AI は Embedding と Reranker に対応していません |
検証例：同じ OpenAI 互換モデル中継サービス経由で呼び出した場合、Cohere Embed v4 は利用できました。Cohere Embed Multilingual v3 は `encoding_format: base64` に、Amazon Titan Text Embeddings V2 は `truncate_prompt_tokens` に対応していないため、この環境ではどちらも Embedding として利用できませんでした。
## よくある質問
**ナレッジベース検索と FAQ 検索が失敗しますが、他の機能は正常です。**\
まず Reranker の URL に余分な `/v1` が付いていないか確認してください。修正後にモデル設定を再読み込みし、機能受入テストを再実行して確認してください。
**外部モデルサービスに接続した後、ナレッジベースの全ファイルが「解析失敗」になります。**\
多くの場合、Embedding が原因です。モデルサービスが上記の 2 つのパラメーターに対応していることと、名前にコロンが含まれる場合にインデックス名を指定していることを確認してください。
**異なる質問に同じ回答が返ります。**\
モデルサービスが正しく応答していません。URL やモデル名の指定ミスがよくある原因です。
## 関連ページ
* [GPU ハードウェア計画](/tech/ja/platform-development/gpu.md)
* [クラウドモデル推論 API サービス](/tech/ja/platform-development/cloud-model-inference-api-service.md)
* [システム要件](/tech/ja/platform-development/system-requirements.md)
* ユーザーマニュアルの[モデル呼び出し権限](https://docs.maiagent.ai/org/model-access)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/tech/ja/platform-development/onprem-model-services.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.