Provider Configuration Persistence#

Overview#

RAGFlow stores provider instance credentials in the TenantModelInstance.api_key database column as either a plain string or a JSON-encoded object 1. Providers with multi-field credentials (e.g., MinerU, Azure OpenAI, BaiduYiYan, XunFei Spark) pack all credential fields into that single column, requiring symmetric transform functions on both the write (submit) and read (prefill) paths.

The api_key Column and Packing#

On save, the backend serializes a str | dict value to string 2:

api_key_str = api_key if isinstance(api_key, str) else json.dumps(api_key)

This happens identically in both create_provider_instance and update_provider_instance. The base_url and region are stored separately in an extra JSON blob, not in api_key 3.

show_provider_instance returns api_key verbatim from the DB column — it may be a raw JSON string or a bare key string.

Frontend Transform Functions#

Every entry in ProviderConfigMap defines two paired transform functions:

The unwrapApiKey function performs the inverse of submitTransform, normalizing three possible shapes returned from the backend back into flat form fields for pre-filling:

1. Raw JSON string '{"api_key":"sk-x","group_id":"123"}' — parsed and spread into flat fields
2. Already-parsed object { api_key, ... } — spread directly
3. Plain bare key "sk-x" — returned as apiKey, no nested fields

This is consumed by useProviderInitialValues, which merges the result into the form's defaultValues.

MinerU Configuration Transform#

MinerU exemplifies providers that pack all fields into api_key as a JSON object. Its submitTransform:

• Spreads all form fields (except instance_name) into a single cfg object
• Converts mineru_delete_output boolean → "1" / "0" string
• Strips mineru_server_url when the backend is not vlm-http-client
• Sets api_key: cfg and base_url: ''

The fields packed into api_key are consumed at runtime by MinerUOcrModel.__init__(), which reads them as lowercase keys.

MinerU form fields and their DB keys 4:

Other Providers with Packed Credentials#

The same pattern applies 5:

• Azure OpenAI — packs { api_key, api_version } into api_key when api_version is set 6
• BaiduYiYan — packs { yiyan_ak, yiyan_sk } 7
• XunFei Spark — packs { spark_api_password, spark_app_id, spark_api_secret, spark_api_key } 8
• PaddleOCR — packs { paddleocr_api_url, paddleocr_access_token, paddleocr_algorithm } 9
• OpenDataLoader — packs { opendataloader_apiserver, opendataloader_api_key } 10

Providers that use a plain string key (e.g., VolcEngine, most OpenAI-compatible providers) use the generic path in buildApiKeyValue / unwrapApiKey and do not need a submitTransform.

Adding a New Provider with Packed Credentials#

1. Add an entry to ProviderConfigMap with:
   • fields: declare each custom field
   • submitTransform: pack fields into api_key as an object, return { instance_name, llm_factory, api_key, base_url, model_info }
   • verifyTransform: pack same fields into { apiKey: cfg, baseUrl, modelInfo }
2. The backend stores the dict as JSON via json.dumps(api_key) — no backend changes needed unless the model class needs to read new keys.
3. Ensure unwrapApiKey covers the new field names, or declare them in API_KEY_NESTED_FIELDS 11 for the generic unwrap path.

Symmetry requirement: submitTransform and unwrapApiKey must produce byte-identical round-trips. The dirty-check baseline comparison in useInstanceSaveState uses JSON.stringify on the payload; asymmetric transforms will cause phantom dirty state on every form open.

Key Source Files#