Migrating from the OpenAI SDK to DeepSeek: five traps
Pointing an OpenAI-SDK codebase at DeepSeek is advertised as a base URL change, and it mostly is. Five details account for nearly every failed migration. None of them are hard; all of them are invisible until a request fails.
1. The base URL suffix
The OpenAI SDK appends /v1 itself in some clients and expects it in the base URL in others. DeepSeek-style endpoints accept both shapes, but gateways differ: one rejects a doubled /v1/v1/, another rejects a missing one.
First action: print the exact URL your client builds — client.base_url — and call it once with curl before running your app.
2. Model names are strings, not constants
Code that hard-codes gpt-4o keeps "working" against some gateways that alias it, then breaks in production when the alias is dropped. DeepSeek's own names are stable across builds; aliases are not part of any contract.
First action: list the models your key can actually call, and use one of those strings verbatim. Model listings are readable without spending tokens.
3. response_format is not universally honoured
response_format={"type":"json_object"} is accepted by the official OpenAI API and quietly ignored or rejected elsewhere depending on the model. A JSON-mode pipeline that worked in staging can emit prose in production.
First action: keep the parser strict. If the model ignores JSON mode, you want a parse error immediately, not a silent format drift.
4. Tool-call field shapes differ
The OpenAI SDK's tool-call shape (tool_calls[].function.arguments as a JSON string) is what DeepSeek returns, but some wrappers double-encode or return arguments as an object. Agents that assume one shape crash on the other.
First action: log the raw tool_calls block on the first successful call, and write the parse against what is actually returned, not what the tutorial says.
5. Streaming chunks are not identical
Streaming deltas differ in two ways that matter: some providers send a final chunk with finish_reason and empty content, and usage appears in different places (a terminal chunk versus a separate field). Token accounting built for one shape miscounts the other.
First action: count tokens from your own accounting on day one, and compare it with the provider's usage report before you trust either.
The migration order that works
- Point one test script at the new endpoint — not the whole app.
- Verify base URL, one chat call, one streaming call, one tool call.
- Compare usage numbers against the console before flipping anything user-facing.
- Move the app, keeping the old provider behind a flag for a week.
Endpoint and client configuration for Cursor, Cline, Dify and the SDKs are in the docs; the model-name caveats are covered in Flash vs Pro.
Questions people actually ask
Is switching to DeepSeek really just a base URL change?
For the happy path, mostly yes. The five exceptions are base URL shape, model names, JSON mode, tool-call field shapes and streaming accounting.
Do OpenAI model aliases like gpt-4o work on DeepSeek?
Some gateways alias them, but aliases are not a contract and can disappear. Use the model names the endpoint lists for your key.
Why does JSON mode break after migration?
response_format is honoured differently across models and providers. Keep the parser strict so a format drift surfaces as an error, not as bad output.
How do I avoid token miscounting after switching?
Stream chunk shapes differ. Count tokens yourself for the first days and reconcile against the provider's usage report.
Should I migrate the whole app at once?
No. Move one test script first, verify chat, streaming and tools, reconcile usage, then migrate behind a flag.
Nova