Choosing Dify workspace default models: what the defaults control and when to set them
Workspace default models are the fallback models that Dify apps inherit when a builder does not pick a model of their own. In a regulated team, this matters because several apps usually share one workspace and builders choose models without review, so the defaults quietly decide which model answers questions, which embedding model indexes documents, and whether speech services are used at all. Dify is an LLM application platform with support for many model providers, and the five default slots are system reasoning, embedding, rerank, speech-to-text and text-to-speech. Set them before the first app is built, because changing them later affects apps that already inherit them.
Each slot controls a different part of the data path. The system reasoning default drives chat, workflow and agent nodes that do not name a model, so it sets most of the inference cost and latency and determines which provider receives user prompts. The embedding default determines which provider sees the text of every document uploaded to a knowledge base, and changing it later means re-indexing existing content. The rerank, speech-to-text and text-to-speech defaults add smaller but real flows: rerank scores retrieved passages, while speech services receive audio or generated text. Confirm for each slot whether the chosen provider or self-hosted endpoint is inside your approved data boundary, and whether the provider's contract covers the data class involved.
The Community edition of Dify is free and limited to a single workspace, so a team that needs separate workspaces for business units or environments will be looking at the Enterprise edition, where the Dify pricing page lists custom pricing. Before you set defaults, decide who may change them, document the approved provider for each slot, and test one representative app per slot against that choice. Ask your implementation partner to include a written default-model register in the scope, so reviewers can see which model each slot uses and why.
Default model slots and when each choice fits
This table compares the five workspace default slots Dify falls back to, showing what each one sees, what drives its cost and latency, and when a hosted endpoint or a self-hosted model fits. Read each row as a question to answer before you set the default, since the slot that touches the most sensitive data is usually the one that needs the closest look. The main takeaway is that embedding and reasoning defaults carry the largest data exposure, so decide those first.
| Default slot | What apps send to it | Cost and latency drivers | When a hosted endpoint fits, or when self-hosted fits |
|---|---|---|---|
| System reasoning | Full prompts, retrieved passages, conversation history and tool outputs for every chat, workflow and agent run | Token volume per run, context length, agent loops that call the model several times, and the response speed of the chosen model | Hosted fits when your contract covers the data and regions you need and volume is moderate. Self-hosted fits when prompts contain regulated records or outputs must stay inside your network |
| Embedding | Document chunks at indexing time and user queries at retrieval time, so knowledge base content leaves your network with each call | Corpus size and re-indexing frequency, chunk count, and query volume. Changing the model later means re-indexing existing content | Hosted fits for public or low-sensitivity content with a stable model choice. Self-hosted fits when knowledge base content must not reach an external API, and you should settle this before indexing begins |
| Rerank | Candidate passages and the user query, sent after initial retrieval to reorder results | Number of candidates scored per query and how often retrieval runs. Usually lighter than reasoning, but it still sees the same passages | Hosted fits when passages are already approved for external processing. Self-hosted fits when retrieved content is sensitive, or when you want retrieval to keep working if an external service is unavailable |
| Speech-to-text | Audio recordings of user input, which may contain personal or customer details | Audio duration and transcription volume. Quality depends on accent, noise and language coverage, so test with your own recordings | Hosted fits for non-sensitive audio where the provider's terms cover recordings. Self-hosted fits when voice data carries personal or health information. Confirm retention terms either way |
| Text-to-speech | Generated text from the app, which may echo sensitive content from knowledge bases or reasoning outputs | Length of generated audio and how often voice responses are used. Less often a sensitivity issue, but output still reflects source data | Hosted fits for scripted or public responses. Self-hosted fits when generated answers include regulated content, or when voice output must stay on your network |
Which factors should drive each default
Each workspace default is a single choice that applies to every app that falls back to it, so one setting can move data, cost, latency and governance at once. The cards below separate the factors that should drive each default, so that the choice for one model type does not hide consequences for another.
Data leaving your network
A default that points to a hosted endpoint sends prompts, retrieved passages and user input outside your boundary on every call that uses it. Embedding and rerank defaults matter most, because they see your full knowledge base content during indexing and retrieval. Confirm, for each default, where the endpoint runs, whether it is inside your cloud account or an external API, and whether the provider retains request data under the terms you have accepted.
Per-call cost versus fixed capacity
Hosted models bill per call or per token, so cost follows usage and rises with every workflow that calls the default. Self-hosted models shift cost toward fixed capacity such as accelerators, hosting and the staff who run them, which is paid whether or not traffic is high. Ask for usage estimates per default and compare them with the capacity you would reserve, rather than comparing a unit price with a monthly hardware bill.
Latency and region
Each call adds network time to the model's own response time, and a default in a distant region can make interactive chat feel slow even when the model is fast. Speech-to-text and text-to-speech defaults are especially sensitive, because audio is streamed and delays are easy to notice. Check which region each endpoint serves, measure from the network where Dify actually runs, and keep defaults for interactive use close to the users and the Dify api service.
Re-indexing when models change
Vectors produced by one embedding model cannot be compared with vectors from another, so changing the embedding default later means re-indexing the knowledge bases built on it. Retrieval quality and storage can also shift with the new model's output size. Treat the embedding default as a long-lived decision, record which model indexed each knowledge base, and plan the re-indexing window before you switch.
Provider contract terms
The contract behind a hosted endpoint decides retention, training use, data location, support and which regulations the provider will sign up to, and those terms apply to every app using the default. A model that is cheap in a self-service account may not carry the terms your legal and compliance teams need. Ask the provider to confirm these terms in writing for each model you plan to set as a default.
Who may change defaults
Changing a default silently alters the behavior, cost and data path of every app that falls back to it, so the people who can change one should be fewer than the people who build apps. Decide which roles may set system defaults, record each change with a reason, and test affected apps after a change. Confirm how your Dify edition controls workspace roles before you assign this responsibility.
How to set workspace defaults in Dify
This sequence confirms the providers and credentials each default slot needs, registers the models, sets the five workspace defaults, and proves that a test app inherits them before any knowledge base is built or any user relies on the configuration.
Inventory the model slots and their providers
The platform administrator lists the five default slots (system reasoning, embedding, rerank, speech-to-text and text-to-speech) and, for each, names the model endpoint that will serve it: a cloud provider contract, an on-premises inference server or a self-hosted embedding service. Record where each endpoint runs, which region or network it sits in and who owns its credentials. Done when every slot has one named provider, one owner and one location written down, and the security or data owner has approved any slot whose traffic leaves your network.
Confirm credentials and network paths for each provider
Before registering anything, the platform team confirms that the Dify api and worker containers can reach each endpoint, that the API key or service identity exists for the target environment, and that outbound calls follow your egress rules. If you use the SSRF proxy, confirm it allows the endpoint address while still blocking internal ranges you do not intend to reach. Check that the SECRET_KEY and encryption settings in your environment file are final, because changing SECRET_KEY after deployment logs out all users. Done when a test request from the Dify host returns a valid response for each endpoint and no key is stored in a shared file.
Register the models in provider settings
A workspace administrator adds each provider in the model provider settings and registers the specific models for each slot, using the exact model identifier the provider or inference server publishes. Confirm the model type is correct: embedding and rerank models must be registered as those types, not as chat models. For self-hosted servers, verify the model name Dify sends matches what the server loads. Done when each registered model shows a successful connection test in the console and appears under the correct model type.
Set the system reasoning and speech defaults
In the workspace default model settings, the administrator selects the system reasoning model, then the speech-to-text and text-to-speech models if your apps use voice. Apps that do not override these choices will inherit them, so pick models that your data classification approves for every app that may use them. Record the chosen model, provider and location in your change log. Done when the console shows the three defaults set and a short test prompt to the reasoning model returns a response from the intended endpoint, confirmed in the provider's usage or server logs.
Set the embedding and rerank defaults before indexing
Set the embedding model default and the rerank model default in the same settings area. Treat the embedding choice as permanent for existing data: vectors created by one embedding model are not compatible with another, so changing it later means re-indexing every knowledge base that uses it. Confirm the embedding model with the owner of the retrieval design before any knowledge base is created or any document is uploaded. Done when a small test document indexed under the default embedding model returns a relevant result from a retrieval test, and the model name is documented as the approved embedding model for the workspace.
Create a test app that inherits the defaults
Create a test app in a non-production workspace without overriding any model setting, so it uses the workspace defaults. The App management documentation describes how apps use these defaults and where a per-app model can override them. Run a reasoning prompt, a voice input and output check if applicable, and a retrieval query against the test knowledge base. Check the provider logs or the Dify usage view to confirm each call went to the endpoint you recorded in the first step. Done when every call is traced to the approved endpoint and no call falls back to an unexpected provider.
Record the defaults and re-test after changes
Save the final default configuration (slot, provider, model identifier, location and owner) in your configuration records and link it to the change ticket. Repeat the test app check after every Dify upgrade, provider key rotation or change to an endpoint, because provider or model updates can alter behavior and cost. Confirm with the Dify upgrade guidance for the target version that model provider settings still load correctly. Done when the record matches the console settings and the most recent test run passed.
How the right defaults differ by team situation
A single team running the self-hosted Community edition usually has one workspace and one set of credentials, so the defaults are a team decision rather than a governance one. The main risk is that a default chosen for convenience quietly sends content to an external API that nobody reviewed. Illustrative example: a five-person team sets its system reasoning model to a hosted provider and its embedding model to the provider's default, then later learns that every uploaded document was embedded externally.
- Reasoning default: Pick one hosted or local chat model and record why it was chosen, including its context limits and cost per call.
- Embedding default: Choose the embedding model before uploading documents, because changing it later means re-indexing existing knowledge bases.
- Rerank and speech defaults: Leave these unset unless an app needs them, so that no audio or retrieval traffic goes to a provider by accident.
- Key ownership: Confirm who holds the provider key and whether it is shared between development and production apps.
- Community limits: Remember that the Community edition is limited to a single workspace, so the defaults apply to everything on the instance.
Before saving defaults, check which provider each model call reaches and write that list down for the team.
A regulated team with a hosted provider contract is usually bound by the terms that provider agreed to, and the defaults must match those terms. The reasoning, embedding, rerank, speech-to-text and text-to-speech defaults each send a different category of data to the provider, so each one needs its own review. Illustrative example: a bank's compliance team approves a chat model under an enterprise agreement but finds that the speech-to-text default points to a consumer endpoint with different retention terms.
- Contracted endpoints only: Map every default to the exact deployment or endpoint covered by the contract, not to a generic provider name.
- Region and retention: Confirm the processing region, data retention and whether provider logs are kept for each model type.
- Latency and cost: Compare the default chat model against the latency budget of the slowest app, since defaults apply to apps that do not override them.
- Separate environments: Keep test and production keys apart so that a test default cannot reach production data.
- Change control: Route any change to a default through the same review used for a new data flow.
Confirm these points with your provider account team and your privacy and procurement owners before the defaults go live.
A team that keeps all inference on-premises trades provider terms for infrastructure work. Defaults point to internal endpoints, so the questions shift to capacity, model availability and whether every default is reachable from Dify's network position. Illustrative example: an infrastructure team registers a reasoning model on a GPU server, but the embedding default still points to an endpoint on a separate network segment that Dify cannot reach, so retrieval silently fails for one knowledge base.
- Internal endpoints: Set each default to an internal inference endpoint and test it from the Dify api and worker containers, not only from a laptop.
- Outbound filtering: Check that the SSRF_PROXY settings allow the internal endpoint, since the proxy blocks internal and private IP ranges by default.
- Capacity: Confirm that the reasoning model can serve peak concurrency and that the embedding and rerank models run on hardware sized for re-indexing jobs.
- Secrets: Keep the SECRET_KEY stable and store any endpoint credentials under the same secret handling as provider keys.
- Fallbacks: Decide what happens when a default is unavailable, and avoid silently falling back to an external provider.
Confirm endpoint addresses, model names and capacity figures with the infrastructure team and test each default end to end.
Which data leaves your network when defaults point to hosted APIs
Every app that inherits a hosted default sends its traffic to that provider. When the system reasoning model, embedding model, rerank model, speech-to-text or text-to-speech default points to a cloud API, each app that falls back to it transmits the user prompt, the retrieved knowledge base chunks that were placed into the prompt, and any uploaded or recorded audio to that provider's endpoint. The workspace default does not limit this. A developer who builds a new app later inherits the same destination without seeing it in the app's settings. Before you set a default, list which of your apps and knowledge bases will use it, and classify the content those apps touch, because the default determines the outbound destination for all of them at once.
Self-hosted endpoints change where that traffic goes, not whether it is processed. If the defaults point to an inference server, embedding service or speech model running in your network, prompts, chunks and audio stay inside the network boundary you control, subject to your own logging and access controls on that server. Dify's outbound request handling is the other half of this picture. The SSRF_PROXY settings in the Dify environment variables reference route outbound requests through a proxy that blocks internal and private IP ranges, which protects the platform from reaching internal addresses it should not call. It also means that a default pointing at an internal inference host may fail until the proxy policy and internal routing are designed for it. Confirm with your platform team exactly which model endpoints, hostnames and ports the proxy must allow, and test each default from the Dify API container, not from your workstation.
Treat the proxy allowlist as a data flow inventory. Each hosted default you keep needs an explicit outbound rule that your security team has approved, and each self-hosted default needs a route that the proxy permits without opening broad internal ranges. Record the destination for every default, the data classes it may receive, and the review owner, then re-check the list after each Dify upgrade, since release notes change how outbound calls are handled. Your model provider contracts and data processing terms decide what the provider does with that traffic once it arrives, and those terms should be confirmed with the provider and your legal team before a hosted default reaches regulated content.
Security and operational risks of workspace defaults
Workspace default models sit on top of credentials, outbound network paths and app exports that all carry sensitive configuration. The cards below cover the documented Dify controls that protect those pieces and the checks to run when defaults change, after upgrades and before anything leaves the workspace.
Protect SECRET_KEY before first use
The SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, so it is part of your credential chain for every model provider you connect. Changing it after deployment logs out all users, which makes it a decision to set once and store in your secrets manager. Check that it is generated per environment, that it is not copied from a sample file, and that your backup procedure captures it alongside the database.
Choose where workspace encryption keys live
Workspace encryption keys can be stored locally or in Azure Key Vault. Local storage keeps the key material on the Dify host, so its protection depends on host access controls and backups. Azure Key Vault moves custody to a managed service with its own access policies and audit trail. Confirm the option against your key management standard before the first model credential is saved, since moving keys later is a planned change rather than a setting toggle.
Filter outbound requests with SSRF_PROXY
Model calls, tool calls and web fetches leave the Dify host, and the SSRF_PROXY settings route those outbound requests through a proxy that blocks internal and private IP ranges. This limits what a workflow or tool can reach on your network. Review the proxy configuration after each change to endpoints, and confirm that your on-premises inference servers are reachable through an allowed path, since an overly broad block can also break legitimate model calls.
Limit who may change defaults
Default models decide which provider, and therefore which data path, new apps and knowledge bases use. Restrict workspace administration to named owners, and record who may change provider configuration. In Community edition all workspace roles are managed inside Dify, so review membership on a schedule. Enterprise SSO and role controls are the documented route to tying these changes to your identity provider, so confirm which of these controls your edition includes before you rely on them.
Audit default changes after upgrades
Releases arrive about monthly, and each one can change the defaults, environment variables or security behavior that your settings depend on. The Docker Compose docs advise checking .env.example for new variables after an upgrade. After each upgrade, compare the workspace default models, provider configuration and proxy settings against the record you kept, and read the release notes for security changes such as the agent sandbox network isolation added in 1.16.1.
Keep DSL exports free of API keys
Apps can be exported as YAML DSL files that include model parameters, prompts and knowledge base connections, but not third-party API keys, knowledge base content or usage logs. That makes DSL a useful change record for default-dependent apps, but it does not replace a backup. Store exports in version control with a review step, rescan them for secrets before commit, and keep credential recovery separate in your secrets manager.
Questions teams ask before setting Dify default models
What does it cost to set Dify workspace default models?
The software cost depends on the edition. The self-hosted Community edition is free and limited to a single workspace, according to the Dify pricing page, while the self-hosted Enterprise edition is custom priced and adds SSO, multiple workspaces, advanced security, a commercial license and professional support. Model costs are separate and come from your provider contracts or the hardware you run for local models. Engineering cost is driven by how many model types you configure, how many providers you connect and how much evaluation you run before choosing defaults. Ask any partner for a fixed-scope quote that lists each default, each provider account and each evaluation step separately.
How long does it take to choose and set defaults?
The duration depends on how many model types you must decide and how many candidate models you test. Setting a default in the console is quick once the provider or endpoint exists, so most of the time goes to access approvals, data classification, latency testing on representative prompts and sign-off from reviewers. Confirm the schedule with your partner or internal team in writing, and ask which steps depend on your own approvals, such as provider contract changes or network firewall requests.
What must our team provide before defaults can be set?
Plan to provide at least three things: accounts or contracts with each model provider, endpoints for any self-hosted inference servers, and named reviewers who approve the data each model may receive. Reviewers usually include a security owner, a data protection contact and the business owner of the apps that will use the defaults. You also need network access from the Dify host to each endpoint and a decision on where API keys are stored. Ask your partner to list these inputs in the scope document so gaps surface before the build starts.
Can our own team set the default models without a partner?
Yes, if your team has administrator access to the Dify workspace and someone who can run a structured evaluation. The console change itself is simple. The harder work is deciding which model handles reasoning, embeddings, rerank, speech-to-text and text-to-speech, and documenting why, including where data goes and how latency behaves under load. Teams without a model evaluation process often benefit from an outside review of that decision. Keep a written record of each default, its provider and its approver so the decision can be audited later.
What happens to existing apps when a default model changes?
Changing a workspace default affects apps that rely on that default, so existing apps may behave differently after the change. Apps that name a specific model keep that model until someone edits them. Before changing a default, list the apps that inherit it, test their prompts and outputs on the new model, and schedule the change outside peak use. Changing an embedding model is more disruptive than changing a chat model because stored vectors may need to be rebuilt. Confirm the exact behavior for your Dify version in the Dify docs on app management and in your own test workspace.
Should our embedding model be hosted or self-hosted?
Choose a self-hosted embedding model when knowledge base content must not leave your network, and a hosted model when the provider contract already meets your data terms and you want less infrastructure to run. Self-hosting shifts cost to GPU or CPU capacity, patching and monitoring. A hosted model adds per-use fees and a dependency on the provider's data handling terms. Either way, the embedding model decides the vectors you store, so switching later usually means re-indexing the knowledge base. Ask your reviewers to approve the choice before any content is indexed.
Which data leaves our network when a default is a cloud model?
Any text sent to a cloud model leaves your network and passes to that provider under its contract. This includes prompts, retrieved knowledge base passages, and for speech defaults, the audio itself. Confirm the provider's retention and training terms, the region where processing occurs and whether logs are kept. Also check the outbound path, since the Dify SSRF proxy settings govern outbound requests from Dify. Document each default against the data classes it may receive so reviewers can approve it with clear limits.
How DeployOpen scopes and delivers Dify default model settings
DeployOpen plans and delivers the Dify workspace default models as part of a self-hosted Dify deployment inside your own infrastructure. We start from the data your apps handle, the model endpoints your organization has approved, and the cost and latency limits your teams need, then document the choices so your operators can maintain them.
How we scope
- Inventory which apps will use each default: system reasoning, embedding, rerank, speech-to-text and text-to-speech.
- Record which model endpoints are approved for each data classification, including whether any traffic may leave your network.
- Agree the scope in writing before work starts, including which workspaces, environments and providers are covered.
How we build
- Configure workspace default models in a non-production Dify instance and test them against representative app workloads.
- Check that embedding model choice matches the knowledge bases you plan to index, and record re-indexing implications before go-live.
- Verify outbound routing through the SSRF proxy and confirm which endpoints are reachable from the Dify services.
How we hand over
- Document each default model, its provider, the reason it was chosen and the data it may receive.
- Provide a test script or checklist your team can rerun after provider changes, Dify upgrades or key rotation.
- Walk your platform and security teams through the decision record so they can explain the defaults to app owners.
How we support
- Review default model settings after each Dify release, since minor versions arrive roughly monthly and may change provider behavior.
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing.
- Re-evaluate defaults when your approved model list, data classification or cost limits change.
