はじめに
Dify で OpenAI 互換のモデルを追加するとき、私は最初に少し混乱しました。API key、base URL、model name、Dify 側の表示名が同じ画面に並ぶので、どれをどこまで含めるのかを雑に考えると後で切り分けが面倒になります。
この記事では、Flatkey AI の OpenAI 互換ルーターを例に、Dify の OpenAI-API-compatible モデル設定を表に分けてから疎通する流れを残します。Flatkey と Dify の公式なワンクリック連携を紹介する記事ではなく、OpenAI 互換 provider として普通に設定するメモです。
3行まとめ
- Dify 側の
API endpoint URLには base URL だけを入れる -
Model Nameと、必要ならmodel name for API endpointに実際の model ID を入れる - 先に
/v1/modelsと小さい chat request で、key、base URL、model name を確認しておく
環境
今回確認した時点のメモです。Dify は plugin の UI が変わる可能性があるので、自分の環境では表示名を見直してください。
| 項目 | 値 |
|---|---|
| Dify plugin | OpenAI-API-compatible |
| plugin version | 0.0.54 |
| base URL | https://router.flatkey.ai/v1 |
| model | gpt-5.4-mini |
| mode | Chat |
記事中の API key はすべて伏せています。スクリーンショットもレビュー用の redacted example です。
レビュー用の redacted setting image: qiita_issue_123_dify_openai_compatible_redacted_settings.png
Dify 側の項目を先に分ける
Dify の公式 plugin 定義を見ると、OpenAI 互換 provider には少なくとも次のような項目があります。ここを先に表にしておくと、かなり落ち着いて設定できます。
| Dify の項目 | 入れるもの | 今回の例 |
|---|---|---|
| Model Type | 使うモデル種別 | LLM |
| Model Name | Dify 側で追加するモデル名 | gpt-5.4-mini |
| API Key | provider に渡す key | sk-fk-... |
| API endpoint URL | OpenAI 互換の base URL | https://router.flatkey.ai/v1 |
| model name for API endpoint | endpoint に送る model 名。空なら Model Name を使う挙動 | 空、または gpt-5.4-mini
|
| Completion mode | chat/completions か completions か | Chat |
私が混ぜそうになったのは、API endpoint URL に /chat/completions まで入れることでした。Dify の plugin 側では base URL として扱われ、Chat の場合は呼び出し時に chat/completions 側へ進むため、ここでは /v1 までにしておくのが自然だと思います。
Flatkey 側で model name を確認する
Dify の設定画面に行く前に、Flatkey 側で model name が見えているかを確認しました。アカウントごとに見えるモデルは変わるので、記事や README からコピーした名前だけで進めない方が安全です。
export BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_API_KEY="sk-fk-..."
curl -sS "$BASE_URL/models" \
-H "Authorization: Bearer $FLATKEY_API_KEY"
私の確認時点では、/v1/models が HTTP 200 で返り、gpt-5.4-mini が見えていました。ここで見えない model name を Dify に入れても、後で model_not_found 系の切り分けになるだけなので、先に見るようにしています。
Dify に入れる値
今回の最小設定はこの形にしました。
Model Type: LLM
Model Name: gpt-5.4-mini
API Key: sk-fk-...
API endpoint URL: https://router.flatkey.ai/v1
model name for API endpoint: gpt-5.4-mini
Completion mode: Chat
Model context size: 4096
Upper bound for max tokens: 4096
Compatibility mode: OpenAI compatible
model name for API endpoint は optional ですが、私は読み返したときに迷わないよう、最初は明示しておく派です。Dify 上の表示名と endpoint に渡す model name を分けたい場合にも、この欄を使うと意図が残ります。
小さく疎通する
Dify に入れる前後で、同じ値を curl でも一度だけ試しておくと、Dify 固有の問題なのか、provider 側の問題なのかを分けやすいです。
curl -sS "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4-mini",
"messages": [
{ "role": "user", "content": "Reply only: ok" }
],
"max_tokens": 8
}'
この確認では HTTP 200、chat.completion、本文 ok、usage.total_tokens あり、というところまで見ました。Dify の画面だけで試すより、まず HTTP と model name の組み合わせが生きていることを見てから進む方が、私にはわかりやすかったです。
ハマったところ
一番大きいのは、base URL と endpoint URL の言葉が近いところです。https://router.flatkey.ai/v1/chat/completions をそのまま入れたくなりますが、Dify の API endpoint URL には base URL を入れる、と覚えた方がよさそうです。
もう一つは、Dify 上の Model Name が人間向けの表示名にも見えるところです。plugin の実装では endpoint_model_name があればそちらを使い、なければ model を使う流れがあるので、表示名と実際に送る model name を分けたいなら明示的に分けるのが安全だと思います。
あとは、model context size や max tokens も最初から盛りすぎないことにしました。まずは 4096 など控えめな値で通して、必要になったらモデルの仕様に合わせて調整する方が、失敗時の変数が少なくて済みます。
まとめ
Dify の OpenAI 互換モデル設定では、次の 4 つを分けて持つだけでだいぶ見通しがよくなりました。
| 見るもの | 例 |
|---|---|
| provider | OpenAI-API-compatible |
| base URL | https://router.flatkey.ai/v1 |
| model name | gpt-5.4-mini |
| API key | sk-fk-... |
Flatkey AI は OpenAI 互換の base URL と Bearer key で呼べるので、Dify の generic な OpenAI 互換 provider からも同じ考え方で整理できます。ただし、使える model name は自分のアカウントや時期で変わるので、/v1/models やダッシュボードで確認してから入れるのがよいと思います。
参考
- Dify Marketplace: OpenAI-API-compatible plugin
- Dify official plugin repository
- Flatkey AI
おわりに
Dify の設定画面で詰まったと思っていたものが、実は base URL と model name の取り違えだった、というのは普通にありそうです。私も慣れているつもりで普通に混ぜかけました。
UI や plugin version によって表示が違うところもあると思うので、間違いあったらコメントください。よろしくお願いします。