docs: surface per-provider AI model override env vars - #290
Merged
paulocastellano merged 4 commits intoAug 26, 2026
Merged
Conversation
.env.example only showed AI_TEXT_PROVIDER/AI_IMAGE_PROVIDER/ AI_AUDIO_PROVIDER (which provider to use), never the per-provider model overrides (OPENAI_IMAGE_MODEL, GEMINI_AUDIO_MODEL, etc.) that config/ai.php already wires up for every provider capability. A self-hoster reading only .env.example had no way to discover these existed. These aren't new: laravel/ai already resolves each capability's model independently per provider (confirmed in vendor - e.g. OpenAiProvider::defaultImageModel() falls back to a hardcoded image model, never to the text model), so there was never actually a text-model fallback bug to fix in code. The gap was purely that the override knobs were invisible outside of reading config/ai.php's source directly.
There was a problem hiding this comment.
Pull request overview
This PR updates .env.example to better document existing laravel/ai environment variables by surfacing optional, per-provider model override env vars (rather than introducing global AI_IMAGE_MODEL / AI_AUDIO_MODEL knobs).
Changes:
- Adds an “AI Model Overrides (optional)” block with commented-out per-provider
*_MODELoverrides near the existingAI_*_PROVIDERsettings. - Documents that model defaults are capability-specific and (per the PR description) do not fall back from image/audio to text models.
- Notes Ollama’s lack of image/audio support in
laravel/ai.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The override block landed with bare variable names and only covered the five providers whose API keys were already in .env.example. Filled in what a self-hoster still could not discover: - Example values on every model override, taken from laravel/ai's current per-capability defaults, so the ID format is visible (an Ollama tag, an OpenRouter vendor/model path and a bare OpenAI ID look nothing alike). - The keys and URLs for the providers .env.example already advertises as valid but never documented: XAI, GROQ, MISTRAL, DEEPSEEK, OLLAMA_URL and the openai-compatible endpoint. Ollama was the scenario in the original report and OLLAMA_URL matters more there than OLLAMA_TEXT_MODEL does. - GROQ/MISTRAL/DEEPSEEK text models, missing while their providers were listed as options. - openai-compatible has no built-in default model and throws without OPENAI_COMPATIBLE_TEXT_MODEL, so that one is flagged as required. - Corrected the audio provider list: gemini and openrouter implement AudioProvider too. The image and audio lists are no longer written as exhaustive. - Mirrored all of it into docker/.env.docker.example, which carried the same block untouched and is the file Docker self-hosters copy. Its OLLAMA_URL points at the host instead of localhost.
Contributor
|
@HafizMMoaz i have improved your pull requested and merged it, thank you! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Investigated this expecting to add
AI_IMAGE_MODEL/AI_AUDIO_MODELconfig as suggested, but found the underlying premise doesn't hold up
against the actual
laravel/aipackage behavior - so this PR doessomething narrower and, I think, more correct.
What I found
config/ai.phpalready defines a model override per provider, percapability -
OPENAI_IMAGE_MODEL,OPENAI_AUDIO_MODEL,GEMINI_IMAGE_MODEL,XAI_IMAGE_MODEL,OPENROUTER_IMAGE_MODEL,OPENROUTER_AUDIO_MODEL,ELEVENLABS_AUDIO_MODEL, etc. - andapp/Services/Ai/AiImageClient.phpalready callsImage::of()through that config.
laravel/aivendor source directly (
OpenAiProvider::defaultImageModel(),OpenRouterProvider::defaultImageModel(), etc.) and each provider'simage/audio default falls back to a hardcoded image/audio model
when unset, never to that provider's text model.
AI_IMAGE_MODEL(as suggested) would actually be aworse fit than what exists - model IDs aren't portable across
providers (
gpt-image-2vs.google/gemini-3.1-flash-image-previewvs. an Ollama tag), so a per-provider override is the correct shape,
not a regression to fix.
laravel/aiatall (confirmed in vendor - only
TextProvider/EmbeddingProviderare implemented), so no config change here can make Ollama do image
or audio generation. OpenRouter, unlike Ollama, already implements
both.
The actual gap:
.env.exampleonly showsAI_TEXT_PROVIDER/AI_IMAGE_PROVIDER/AI_AUDIO_PROVIDER(which provider to route to)and never mentions any of the per-provider model overrides that
already exist and work. A self-hoster reading only
.env.examplewould have no way to discover them without reading
config/ai.phpsource - which lines up with the issue's report even though the
mechanism it assumed isn't what's actually happening.
Change
Added the per-provider model override variables (commented out, as
optional) right after the existing
AI_*_PROVIDERblock in.env.example, with a note on Ollama's text-only support.Test plan
No code paths changed - this is
.env.exampledocumentation only.Verified
config/ai.php's existing wiring and the vendorlaravel/aiprovider classes referenced above by reading them directly rather than
assuming.
Addresses #225 - happy to also add
AI_IMAGE_MODEL/AI_AUDIO_MODELglobals if you'd still prefer those for convenience, but wanted to flag they'd need to pick a provider's model format, which only works cleanly if there's exactly one image/audio provider configured