Plugin Model Caching#

Plugin model caching covers how Dify discovers, caches, and refreshes the set of model providers contributed by installed plugins for a given tenant. The system has two separate cache layers — a backend Redis cache for provider lists and model schemas, and a frontend React Query cache for UI state — with explicit invalidation hooks connecting plugin lifecycle events (install, upgrade, uninstall) to both layers.

The entire backend cache is owned by PluginService in api/core/plugin/plugin_service.py. Centralizing ownership here keeps tenant isolation and invalidation logic in one place; all plugin lifecycle mutations (install, uninstall, upgrade) call invalidate_plugin_model_providers_cache() before returning 1 2 3 4.

Redis Key Structure#

Four Redis key families control the provider cache per tenant 5:

Default TTL for the provider cache is 24 hours (PLUGIN_MODEL_PROVIDERS_CACHE_TTL=86400) 6. The lock TTL is 30 seconds; waiters time out after 2 seconds before falling back to a direct daemon call 7.

Large payloads (≥ 64 KB) are transparently compressed with zstd level-1 before storage, identified by the \x00dify-plugin-model-providers-zstd-v1: prefix. Readers accept both compressed and legacy plain-JSON payloads to support rolling upgrades 8 9.

Cache Read Path (fetch_plugin_model_providers)#

fetch_plugin_model_providers() implements a generation-aware, single-flight read loop:

1. Read the current generation counter from Redis.
2. Attempt to load the cached provider list for that generation.
3. On a cache hit → return immediately.
4. On a cache miss with a valid generation → acquire the per-generation distributed lock and re-check the cache inside the lock (double-checked locking).
5. If the lock is acquired and the cache is still empty → fetch from the plugin daemon, store, and return.
6. If the lock cannot be acquired within 2 seconds → fall back to a direct daemon fetch (no caching) 10.

This pattern was refined in PR #38226 to separate the lock's lease TTL from the waiter deadline and remove a per-worker memory cache, making Redis the single source of truth.

PluginModelRuntime.fetch_model_providers() delegates directly to this service method 11, so all model runtime paths share the same cache.

Cache Invalidation Path#

invalidate_plugin_model_providers_cache() uses a Redis pipeline to atomically:

1. Delete the (legacy, non-generation) base cache key.
2. Increment the generation counter (INCR), which renders any in-flight reads for the old generation stale.

Any waiter that races the increment and re-reads a changed generation will loop back to the top of fetch_plugin_model_providers 12, so no stale payload is ever served.

Invalidation is triggered by:

• Every terminal plugin task status 13
• All install, upgrade, and uninstall paths
• When list_by_category is called for model plugins (category=Model) and the system detects remote debug plugin state has changed by comparing the current list of remote plugins to the cached marker; if the remote plugin marker differs or if remote plugins are present but not represented in the cached providers, the cache is invalidated and the new marker is stored — this ensures that model provider caches are refreshed when debugging remote model plugins

Model Schema Cache (get_model_schema)#

A separate, per-model Redis cache stores AIModelEntity schemas with a 1-hour TTL (PLUGIN_MODEL_SCHEMA_CACHE_TTL=3600) 14. The cache key is scoped by tenant_id:provider:model_type:model:user_id plus an MD5 hash of sorted credential key-value pairs, preventing cross-credential cache collisions 15. Invalid (schema-parse-error) entries are deleted on read 16.

Frontend React Query Cache#

The frontend maintains a parallel cache in React Query. refreshModelProviders() (defined in provider-context-provider.tsx) calls:

queryClient.invalidateQueries({ queryKey: ['common', 'model-providers'] })

useRefreshPluginList expands this for model-category plugins to also refetch every model-type list (LLM, Embedding, Rerank, TTS, Speech2Text) and default-model selections.

PR #37002 extended this pattern to the plugin detail panel: handlePluginUpdated in use-plugin-operations.ts now invalidates:

• ['models', 'model-list'] and calls refreshModelProviders() for model plugins
• ['tools', 'builtin-provider-tools'] for tool plugins
• ['strategy', 'detail'] for agent-strategy plugins

Key Files and Entry Points#