feat(providers): add deepseek responses adapter (#285)

SantiagoDePolonia · claude · web-flow · commit a26fbd1cdef9 · 2026-04-28T00:13:47.000+02:00
* feat(providers): add deepseek responses adapter

* docs(deepseek): add provider guide with reasoning effort mapping

Document DeepSeek V4's two-level reasoning_effort surface and the
low/medium -&gt; high remap so users aren't surprised by the upgrade.
Cross-link from the Codex guide and add a comment on
normalizeReasoningEffort pointing to the user-facing table.

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -23,7 +23,7 @@
 </p>
 
 <p align="center">
-  A fast and lightweight AI gateway written in Go, providing a unified OpenAI-compatible API for OpenAI, Anthropic, Gemini, xAI, Groq, OpenRouter, Z.ai, Azure OpenAI, Oracle, Ollama, and more.
+  A fast and lightweight AI gateway written in Go, providing a unified OpenAI-compatible API for OpenAI, Anthropic, Gemini, DeepSeek, xAI, Groq, OpenRouter, Z.ai, Azure OpenAI, Oracle, Ollama, and more.
 </p>
 
 <a href="docs/dashboard.gif">
@@ -51,6 +51,7 @@ docker run --rm -p 8080:8080 \
   -e OPENAI_API_KEY="your-openai-key" \
   -e ANTHROPIC_API_KEY="your-anthropic-key" \
   -e GEMINI_API_KEY="your-gemini-key" \
+  -e DEEPSEEK_API_KEY="your-deepseek-key" \
   -e GROQ_API_KEY="your-groq-key" \
   -e OPENROUTER_API_KEY="your-openrouter-key" \
   -e ZAI_API_KEY="your-zai-key" \
@@ -90,6 +91,7 @@ Example model identifiers are illustrative and subject to change; consult provid
 | OpenAI        | `OPENAI_API_KEY`                                                  | `gpt-5.5`                          |  ✅  |      ✅      |  ✅   |  ✅   |   ✅    |    ✅    |
 | Anthropic     | `ANTHROPIC_API_KEY`                                               | `claude-sonnet-4-20250514`         |  ✅  |      ✅      |  ❌   |  ❌   |   ✅    |    ✅    |
 | Google Gemini | `GEMINI_API_KEY`                                                  | `gemini-2.5-flash`                 |  ✅  |      ✅      |  ✅   |  ✅   |   ✅    |    ❌    |
+| DeepSeek      | `DEEPSEEK_API_KEY`                                                | `deepseek-v4-pro`                  |  ✅  |      ✅      |  ❌   |  ❌   |   ❌    |    ❌    |
 | Groq          | `GROQ_API_KEY`                                                    | `llama-3.3-70b-versatile`          |  ✅  |      ✅      |  ✅   |  ✅   |   ✅    |    ❌    |
 | OpenRouter    | `OPENROUTER_API_KEY`                                              | `google/gemini-2.5-flash`          |  ✅  |      ✅      |  ✅   |  ✅   |   ✅    |    ✅    |
 | Z.ai          | `ZAI_API_KEY` (`ZAI_BASE_URL` optional)                           | `glm-5.1`                          |  ✅  |      ✅      |  ✅   |  ❌   |   ❌    |    ✅    |
@@ -105,7 +107,9 @@ For Z.ai's GLM Coding Plan, set `ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v
 Configured model lists are available for every provider with
 `<PROVIDER>_MODELS`, for example
 `OPENROUTER_MODELS=openai/gpt-oss-120b,anthropic/claude-sonnet-4` or
-`ORACLE_MODELS=openai.gpt-oss-120b,xai.grok-3`. By default,
+`ORACLE_MODELS=openai.gpt-oss-120b,xai.grok-3`. DeepSeek defaults to
+`https://api.deepseek.com`; set `DEEPSEEK_BASE_URL` only when using a compatible
+proxy or alternate DeepSeek endpoint. By default,
 `CONFIGURED_PROVIDER_MODELS_MODE=fallback` uses those lists only when upstream
 `/models` is unavailable or empty. Set `CONFIGURED_PROVIDER_MODELS_MODE=allowlist`
 to expose only configured models for providers that define a list, skipping
@@ -288,7 +292,7 @@ See [DEVELOPMENT.md](docs/DEVELOPMENT.md) for testing, linting, and pre-commit s
 ### Must Have
 
 - [ ] Intelligent routing
-- [ ] Broader provider support: Oracle model configuration via environment variables, plus Cohere, Command A, Operational, and DeepSeek V3
+- [ ] Broader provider support: Cohere, Command A, and Operational
 - [ ] Budget management with limits per `user_path` and/or API key
 - [ ] Editable model pricing for accurate cost tracking and budgeting
 - [ ] Full support for the OpenAI `/responses` and `/conversations` lifecycle
diff --git a/cmd/gomodel/docs/docs.go b/cmd/gomodel/docs/docs.go
@@ -4355,7 +4355,7 @@ var SwaggerInfo = &swag.Spec{
 	BasePath:         "/",
 	Schemes:          []string{"http"},
 	Title:            "GoModel API",
-	Description:      "High-performance AI gateway routing requests to multiple LLM providers (OpenAI, Anthropic, Gemini, Groq, OpenRouter, Z.ai, xAI, Oracle, Ollama). Drop-in OpenAI-compatible API.",
+	Description:      "High-performance AI gateway routing requests to multiple LLM providers (OpenAI, Anthropic, Gemini, Groq, OpenRouter, DeepSeek, Z.ai, xAI, MiniMax, Oracle, Ollama). Drop-in OpenAI-compatible API.",
 	InfoInstanceName: "swagger",
 	SwaggerTemplate:  docTemplate,
 	LeftDelim:        "{{",
diff --git a/cmd/gomodel/main.go b/cmd/gomodel/main.go
@@ -18,6 +18,7 @@ import (
 	"gomodel/internal/providers"
 	"gomodel/internal/providers/anthropic"
 	"gomodel/internal/providers/azure"
+	"gomodel/internal/providers/deepseek"
 	"gomodel/internal/providers/gemini"
 	"gomodel/internal/providers/groq"
 	"gomodel/internal/providers/minimax"
@@ -73,7 +74,7 @@ func startApplication(application lifecycleApp, addr string) error {
 
 // @title          GoModel API
 // @version        1.0
-// @description    High-performance AI gateway routing requests to multiple LLM providers (OpenAI, Anthropic, Gemini, Groq, OpenRouter, Z.ai, xAI, MiniMax, Oracle, Ollama). Drop-in OpenAI-compatible API.
+// @description    High-performance AI gateway routing requests to multiple LLM providers (OpenAI, Anthropic, Gemini, Groq, OpenRouter, DeepSeek, Z.ai, xAI, MiniMax, Oracle, Ollama). Drop-in OpenAI-compatible API.
 // @BasePath       /
 // @schemes        http
 // @securityDefinitions.apikey BearerAuth
@@ -119,6 +120,7 @@ func main() {
 	factory.Add(azure.Registration)
 	factory.Add(oracle.Registration)
 	factory.Add(anthropic.Registration)
+	factory.Add(deepseek.Registration)
 	factory.Add(gemini.Registration)
 	factory.Add(groq.Registration)
 	factory.Add(minimax.Registration)
diff --git a/config/config.example.yaml b/config/config.example.yaml
@@ -264,10 +264,11 @@ providers:
   #     - openai.gpt-oss-120b
   #     - xai.grok-3
 
-  # Example: DeepSeek (OpenAI-compatible)
+  # Example: DeepSeek. GoModel translates /v1/responses requests to DeepSeek
+  # chat completions because DeepSeek does not expose a native Responses API.
   # deepseek:
-  #   type: "openai"
-  #   base_url: "https://api.deepseek.com/v1"
+  #   type: "deepseek"
+  #   base_url: "https://api.deepseek.com"
   #   api_key: "${DEEPSEEK_API_KEY}"
 
   # Example: local Ollama server with explicit per-model metadata.
diff --git a/config/config_test.go b/config/config_test.go
@@ -18,6 +18,7 @@ func clearProviderEnvVars(t *testing.T) {
 		"OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODELS",
 		"ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_MODELS",
 		"GEMINI_API_KEY", "GEMINI_BASE_URL", "GEMINI_MODELS",
+		"DEEPSEEK_API_KEY", "DEEPSEEK_BASE_URL", "DEEPSEEK_MODELS",
 		"XAI_API_KEY", "XAI_BASE_URL", "XAI_MODELS",
 		"GROQ_API_KEY", "GROQ_BASE_URL", "GROQ_MODELS",
 		"OPENROUTER_API_KEY", "OPENROUTER_BASE_URL", "OPENROUTER_MODELS", "OPENROUTER_SITE_URL", "OPENROUTER_APP_NAME",
diff --git a/docs/about/roadmap.mdx b/docs/about/roadmap.mdx
@@ -7,7 +7,7 @@ icon: "list-todo"
 ### Must Have
 
 - [ ] Intelligent routing
-- [ ] Broader provider support: Oracle model configuration via environment variables, plus Cohere, Command A, Operational, and DeepSeek V3
+- [ ] Broader provider support: Cohere, Command A, and Operational
 - [ ] Budget management with limits per `user_path` and/or API key
 - [ ] Editable model pricing for accurate cost tracking and budgeting
 - [ ] Full support for the OpenAI `/responses` and `/conversations` lifecycle
diff --git a/docs/adr/0001-explicit-provider-registration.md b/docs/adr/0001-explicit-provider-registration.md
@@ -2,7 +2,7 @@
 
 ## Context
 
-GoModel supports multiple LLM providers, including OpenAI, Anthropic, Gemini, xAI, Groq, OpenRouter, Z.ai, Azure OpenAI, Oracle, Ollama, and custom OpenAI-compatible endpoints. Each provider must be registered with the factory before use.
+GoModel supports multiple LLM providers, including OpenAI, Anthropic, Gemini, DeepSeek, xAI, Groq, OpenRouter, Z.ai, Azure OpenAI, Oracle, Ollama, and custom OpenAI-compatible endpoints. Each provider must be registered with the factory before use.
 
 ## Decision
 
diff --git a/docs/advanced/configuration.mdx b/docs/advanced/configuration.mdx
@@ -181,6 +181,7 @@ Set these to automatically register providers. No YAML configuration required.
 | `OPENAI_API_KEY`     | OpenAI                                             |
 | `ANTHROPIC_API_KEY`  | Anthropic                                          |
 | `GEMINI_API_KEY`     | Google Gemini                                      |
+| `DEEPSEEK_API_KEY`   | DeepSeek                                           |
 | `OPENROUTER_API_KEY` | OpenRouter                                         |
 | `ZAI_API_KEY`        | Z.ai                                               |
 | `XAI_API_KEY`        | xAI (Grok)                                         |
@@ -190,7 +191,7 @@ Set these to automatically register providers. No YAML configuration required.
 | `OLLAMA_BASE_URL`    | Ollama (no API key needed)                        |
 | `VLLM_BASE_URL`      | vLLM (no API key needed unless upstream requires) |
 
-Most providers can use a custom base URL via `<PROVIDER>_BASE_URL` (for example `OPENAI_BASE_URL`). OpenRouter defaults to `https://openrouter.ai/api/v1` and can be overridden with `OPENROUTER_BASE_URL`. Z.ai defaults to `https://api.z.ai/api/paas/v4`; set `ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4` for the GLM Coding Plan endpoint. vLLM defaults to `http://localhost:8000/v1` when `VLLM_API_KEY` is set, but keyless deployments should set `VLLM_BASE_URL` explicitly to register the provider. Azure uses `AZURE_BASE_URL` for its deployment base URL and accepts an optional `AZURE_API_VERSION` override; otherwise it defaults to `2024-10-21`. Oracle requires `ORACLE_BASE_URL` because its OpenAI-compatible endpoint is region-specific.
+Most providers can use a custom base URL via `<PROVIDER>_BASE_URL` (for example `OPENAI_BASE_URL`). DeepSeek defaults to `https://api.deepseek.com`; set `DEEPSEEK_BASE_URL` only for a compatible proxy or alternate DeepSeek endpoint. OpenRouter defaults to `https://openrouter.ai/api/v1` and can be overridden with `OPENROUTER_BASE_URL`. Z.ai defaults to `https://api.z.ai/api/paas/v4`; set `ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4` for the GLM Coding Plan endpoint. vLLM defaults to `http://localhost:8000/v1` when `VLLM_API_KEY` is set, but keyless deployments should set `VLLM_BASE_URL` explicitly to register the provider. Azure uses `AZURE_BASE_URL` for its deployment base URL and accepts an optional `AZURE_API_VERSION` override; otherwise it defaults to `2024-10-21`. Oracle requires `ORACLE_BASE_URL` because its OpenAI-compatible endpoint is region-specific.
 
 Every provider type also accepts a comma-separated configured model list via
 `<PROVIDER>_MODELS`, for example `OPENROUTER_MODELS`, `ORACLE_MODELS`,
@@ -311,6 +312,7 @@ The simplest way to add providers. GoModel checks for well-known API key environ
 export OPENAI_API_KEY="sk-..."      # Registers "openai" provider
 export ANTHROPIC_API_KEY="sk-ant-..." # Registers "anthropic" provider
 export GEMINI_API_KEY="..."          # Registers "gemini" provider
+export DEEPSEEK_API_KEY="..."        # Registers "deepseek" provider
 export XAI_API_KEY="..."             # Registers "xai" provider
 export GROQ_API_KEY="gsk_..."        # Registers "groq" provider
 export OPENROUTER_API_KEY="sk-or-..." # Registers "openrouter" provider
@@ -381,6 +383,12 @@ providers:
       - openai.gpt-oss-120b
       - xai.grok-3
 
+  # Add DeepSeek. GoModel translates /v1/responses to DeepSeek chat completions.
+  deepseek:
+    type: deepseek
+    base_url: "https://api.deepseek.com"
+    api_key: "..."
+
   # Add a vLLM OpenAI-compatible server
   vllm:
     type: vllm
diff --git a/docs/docs.json b/docs/docs.json
@@ -86,6 +86,7 @@
                 "pages": [
                     "guides/openclaw",
                     "guides/oracle",
+                    "guides/deepseek",
                     "guides/vllm",
                     "guides/multiple-ollama",
                     "guides/claude-code",
diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx
@@ -7,9 +7,9 @@ icon: "rocket"
 ## Run GoModel in 30 Seconds
 
 GoModel is an OpenAI-compatible AI gateway. You can connect one endpoint and
-route traffic across OpenAI, Anthropic, Gemini, xAI, Groq, OpenRouter, Z.ai,
-Azure OpenAI, Oracle, Ollama, and more while keeping auth, audit logs, and admin
-visibility in one place.
+route traffic across OpenAI, Anthropic, Gemini, DeepSeek, xAI, Groq, OpenRouter,
+Z.ai, Azure OpenAI, Oracle, Ollama, and more while keeping auth, audit logs, and
+admin visibility in one place.
 
 ### 1. Start GoModel
 
@@ -26,9 +26,10 @@ docker run --rm -p 8080:8080 \
 
 <Note>
   Set at least one provider credential or base URL
-  (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`,
-  `GROQ_API_KEY`, `OPENROUTER_API_KEY`, `ZAI_API_KEY`, `AZURE_API_KEY` +
-  `AZURE_BASE_URL`, `ORACLE_API_KEY` + `ORACLE_BASE_URL`,
+  (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`,
+  `DEEPSEEK_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY`,
+  `ZAI_API_KEY`, `AZURE_API_KEY` + `AZURE_BASE_URL`,
+  `ORACLE_API_KEY` + `ORACLE_BASE_URL`,
   `OLLAMA_BASE_URL`) or GoModel will have no models to route. GoModel also
   works well with additional OpenAI-compatible providers out of the box.
 </Note>
diff --git a/docs/guides/codex.mdx b/docs/guides/codex.mdx
@@ -9,7 +9,7 @@ Responses API.
 
 Flow:
 
-`Codex -> GoModel -> OpenAI`
+`Codex -> GoModel -> upstream model provider`
 
 ## Before you start
 
@@ -97,6 +97,42 @@ The validated result was:
 ok
 ```
 
+## DeepSeek V4
+
+Codex sends `POST /v1/responses`. DeepSeek exposes chat completions instead of
+a native Responses API, so configure the first-class DeepSeek provider and let
+GoModel translate the request.
+
+```yaml
+providers:
+  deepseek:
+    type: deepseek
+    base_url: "https://api.deepseek.com"
+    api_key: "${DEEPSEEK_API_KEY}"
+```
+
+If you previously configured DeepSeek as `type: openai`, change it to
+`type: deepseek` for Codex. The generic OpenAI provider forwards `/responses`
+upstream, while the DeepSeek provider translates `/responses` to
+`/chat/completions`.
+
+See the [DeepSeek guide](/guides/deepseek) for the full reasoning effort
+mapping table (DeepSeek V4 only accepts `high` and `max`, so GoModel maps
+`low` and `medium` up to `high`).
+
+Then use the DeepSeek model name in Codex:
+
+```toml
+model_provider = "gomodel"
+model = "deepseek-v4-pro"
+
+[model_providers.gomodel]
+name = "GoModel"
+base_url = "http://localhost:8080/v1"
+env_key = "OPENAI_API_KEY"
+wire_api = "responses"
+```
+
 ## 5. Check the traffic in GoModel
 
 Open the GoModel dashboard audit logs:
diff --git a/docs/guides/deepseek.mdx b/docs/guides/deepseek.mdx
@@ -0,0 +1,67 @@
+---
+title: "GoModel & DeepSeek"
+description: "Configure DeepSeek V4 in GoModel and understand how reasoning effort is mapped to DeepSeek's reasoning_effort field."
+icon: "brain"
+---
+
+GoModel routes to DeepSeek through DeepSeek's chat completions API. DeepSeek
+does not expose a native Responses API, so GoModel translates `/v1/responses`
+requests to `/chat/completions` automatically.
+
+## 1. Configure DeepSeek
+
+Env-only is enough:
+
+```bash
+export DEEPSEEK_API_KEY="..."
+```
+
+Or in `config.yaml` (not recommended):
+
+```yaml
+providers:
+  deepseek:
+    type: deepseek
+    base_url: "https://api.deepseek.com"
+    api_key: "${DEEPSEEK_API_KEY}"
+```
+
+<Note>
+  If you previously configured DeepSeek as `type: openai`, switch it to `type:
+  deepseek` so GoModel translates `/v1/responses` and remaps reasoning effort.
+  The generic OpenAI provider does neither.
+</Note>
+
+## 2. Reasoning effort mapping
+
+DeepSeek V4 reasoning models accept `reasoning_effort` as a top-level string
+with two levels: `high` and `max`. GoModel accepts the standard OpenAI-style
+levels and remaps them:
+
+| Client sends    | DeepSeek receives |
+| --------------- | ----------------- |
+| `low`           | `high`            |
+| `medium`        | `high`            |
+| `high`          | `high`            |
+| `xhigh` / `max` | `max`             |
+| anything else   | passed through    |
+
+`low` and `medium` are mapped up to `high` because DeepSeek's reasoning models
+do not accept lower levels. If you want to avoid reasoning entirely, omit the
+`reasoning` field instead of passing `low`.
+
+GoModel rewrites the request body so DeepSeek sees a top-level
+`reasoning_effort: "..."` instead of OpenAI's nested
+`"reasoning": {"effort": "..."}` shape. No client change is required.
+
+## Current support
+
+Integrated:
+
+- chat completions and streaming
+- Responses API and streaming (translated to chat completions)
+- model listing through `/models`
+
+Not supported by DeepSeek:
+
+- embeddings (returns an `invalid_request_error`)
diff --git a/docs/openapi.json b/docs/openapi.json
@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.0",
   "info": {
-    "description": "High-performance AI gateway routing requests to multiple LLM providers (OpenAI, Anthropic, Gemini, Groq, OpenRouter, Z.ai, xAI, MiniMax, Oracle, Ollama). Drop-in OpenAI-compatible API.",
+    "description": "High-performance AI gateway routing requests to multiple LLM providers (OpenAI, Anthropic, Gemini, Groq, OpenRouter, DeepSeek, Z.ai, xAI, MiniMax, Oracle, Ollama). Drop-in OpenAI-compatible API.",
     "title": "GoModel API",
     "contact": {},
     "version": "1.0"
diff --git a/helm/Chart.yaml b/helm/Chart.yaml
@@ -1,6 +1,6 @@
 apiVersion: v2
 name: gomodel
-description: High-performance AI gateway for multiple LLM providers (OpenAI, Anthropic, Gemini, Groq, Z.ai, xAI)
+description: High-performance AI gateway for multiple LLM providers (OpenAI, Anthropic, Gemini, DeepSeek, Groq, Z.ai, xAI)
 type: application
 version: 0.1.0
 appVersion: "1.0.0"
diff --git a/helm/README.md b/helm/README.md
@@ -1,6 +1,6 @@
 # GoModel Helm Chart
 
-High-performance AI gateway for multiple LLM providers (OpenAI, Anthropic, Gemini, Groq, Z.ai, xAI, Oracle).
+High-performance AI gateway for multiple LLM providers (OpenAI, Anthropic, Gemini, DeepSeek, Groq, Z.ai, xAI, Oracle).
 
 ## Prerequisites
 
diff --git a/internal/providers/config_test.go b/internal/providers/config_test.go
@@ -27,6 +27,9 @@ var testDiscoveryConfigs = map[string]DiscoveryConfig{
 	"gemini": {
 		DefaultBaseURL: "https://generativelanguage.googleapis.com/v1beta/openai",
 	},
+	"deepseek": {
+		DefaultBaseURL: "https://api.deepseek.com",
+	},
 	"xai": {
 		DefaultBaseURL: "https://api.x.ai/v1",
 	},
@@ -402,6 +405,26 @@ func TestApplyProviderEnvVars_DiscoversOpenRouterFromAPIKey(t *testing.T) {
 	}
 }
 
+func TestApplyProviderEnvVars_DiscoversDeepSeekFromAPIKey(t *testing.T) {
+	t.Setenv("DEEPSEEK_API_KEY", "deepseek-key")
+
+	got := applyProviderEnvVars(map[string]config.RawProviderConfig{}, testDiscoveryConfigs)
+
+	p, exists := got["deepseek"]
+	if !exists {
+		t.Fatal("expected deepseek to be discovered from env var")
+	}
+	if p.APIKey != "deepseek-key" {
+		t.Errorf("APIKey = %q, want deepseek-key", p.APIKey)
+	}
+	if p.Type != "deepseek" {
+		t.Errorf("Type = %q, want deepseek", p.Type)
+	}
+	if p.BaseURL != testDiscoveryConfigs["deepseek"].DefaultBaseURL {
+		t.Errorf("BaseURL = %q, want %q", p.BaseURL, testDiscoveryConfigs["deepseek"].DefaultBaseURL)
+	}
+}
+
 func TestApplyProviderEnvVars_DiscoversZAIFromAPIKey(t *testing.T) {
 	t.Setenv("ZAI_API_KEY", "zai-key")
 
diff --git a/internal/providers/deepseek/deepseek.go b/internal/providers/deepseek/deepseek.go
diff --git a/internal/providers/deepseek/deepseek_test.go b/internal/providers/deepseek/deepseek_test.go
