Connect RAGFlow or Dify to Multiple LLMs with One Key | HopBase

To connect RAGFlow or Dify to multiple LLMs, you need three values: add an "OpenAI-compatible" model provider, set the Base URL to https://api.hop-base.com/v1, paste one HopBase API key, and enter each model ID exactly as GET /v1/models returns it. Put several groups on that key and one knowledge base can use DeepSeek, GPT, GLM, Kimi, Qwen and Gemini side by side; Claude needs the Anthropic provider type instead. Keep your current embedding provider. Give each knowledge-base app its own key with a quota, and cost attribution per app comes for free.

First, to be clear: HopBase is not a built-in provider in RAGFlow or Dify

Neither project currently lists HopBase as a named provider. This guide uses the generic option both of them offer: an OpenAI-compatible API. Menu labels change between versions, so the steps below describe the fields rather than exact UI text.

Step 1: Create a key and confirm the model IDs

1. In the console, create a key and select the groups your knowledge base needs (1 to 10 groups per key). The key can only call models in those groups.
2. Set a quota and an expiry date on the key, and an IP list if you want one (use the egress IP of your RAGFlow or Dify server).
3. List the models this key can reach and copy the full IDs. Do not retype them or add or drop suffixes:

curl https://api.hop-base.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

A misspelled model, or one outside the key's groups, returns 404 model_not_found.

Step 2: Configure RAGFlow

1. Open the Model providers page under user settings.
2. Pick the OpenAI-compatible provider type and create an instance.
3. Set Base URL to https://api.hop-base.com/v1 (with /v1) and API Key to sk-your-key.
4. Add a model: the model name is the ID from /v1/models, the type is chat; choose a vision type only for models that accept images.
5. Enable tool calling only if the model supports it. Verify each model, then save.
6. In the default model settings, point the default chat model at the new model. RAGFlow also requires a default embedding model; leave that on your existing provider.

Step 3: Configure Dify

1. As the workspace owner or an admin, open model provider management and install the OpenAI-compatible provider plugin.
2. Add a model: model name is the full ID, API key is sk-your-key, API endpoint is https://api.hop-base.com/v1.
3. Set the context size from the model's spec. Turn on vision support only for models that accept images.
4. Save, then select the model in your knowledge-base app or the LLM node of a workflow.

What about Claude?

Claude is served only over the Anthropic Messages protocol (/v1/messages); calling it through the OpenAI-compatible type returns 404. Use the Anthropic provider type instead, with Base URL https://api.hop-base.com (no /v1) and a key that includes a Claude group. If the Anthropic form in your version has no editable Base URL field, that version cannot reach Claude through HopBase; use GPT or DeepSeek over the OpenAI-compatible type in the meantime.

Pick models by role

Role	Example model IDs (confirm with /v1/models)	Notes
Everyday Q&A	deepseek-v4.1-flash, qwen3.8-flash, gpt-6-luna	Low cost, suits high-volume retrieval answers
Hard reasoning / summaries	gpt-6-sol, qwen3.8-max, Claude (Anthropic type)	Reserve for apps where quality matters most
Long documents (full contracts, manuals)	kimi-k3, glm-5.3-flash, deepseek-v4.1-flash	All about 1M context; kimi-k3 caps output at 32,768 tokens
Images and scanned pages	glm-5.3-flash, deepseek-v4.1-flash	Both accept image URLs and base64
Images (base64 only)	kimi-k3	Accepts base64 images; image URLs return 400

Switch on vision only for models that read images. For example, deepseek-v4-pro-202606 does not accept images: a request with one returns 400 before reaching the model and is not billed.

Embeddings and rerank: keep your current provider

HopBase's public model catalog does not include embedding models. Keep vectorizing and reranking with the provider you use today. Changing the embedding model usually means re-indexing; changing the chat model does not. That is the practical upside of moving only the chat side to HopBase: you can swap models without touching existing vectors.

One key per knowledge-base app, cost split per app

1. One app, one key: support KB, legal KB and engineering docs each get their own key. A leak or runaway loop stops at one key.
2. Key quota: once a key's quota is used up, requests are refused before processing (HTTP 402 insufficient_quota), so one app cannot drain the whole budget.
3. Departments: a key with no member attached can be assigned straight to a department, with a department quota that resets on your billing day (any day from the 1st to the 28th).
4. Export and reconcile: filter the usage page by key or department and export CSV; every row recomputes as official cost × discount ÷ exchange rate = amount charged. Failed requests are not billed.

For per-model parameter quirks (such as Kimi K3's include_reasoning), see One OpenAI-compatible key for DeepSeek, Qwen, GLM, Kimi and Doubao. Base URL rules are in the Base URL docs, and client fields in Third-party clients.

FAQ

Why does RAGFlow return 404 when I add a model?

Check three things: the model name matches /v1/models exactly; the Base URL ends in /v1; and Claude is not configured under the OpenAI-compatible type (Claude needs the Anthropic type, without /v1).

Can Dify use Claude, GPT and DeepSeek at the same time?

Yes. Put the matching groups on one key. GPT and DeepSeek go through the OpenAI-compatible type, Claude through the Anthropic type, and both providers share the same key.

Is our knowledge-base data used for training?

No. Prompts and outputs are used only to complete the request; they are not kept as business data and not used for training. Billing metadata is kept for invoices and audit, and all traffic uses TLS.

Sign up for HopBase and issue the first key for your knowledge base