SDK and framework migration

Move an existing application from a provider or another gateway.

Start migration by inspecting the HTTP requests your application actually makes, not just the SDK name. This site’s Python / TypeScript dependencies are pinned for reproducibility. Recheck default retries, parameters, and resource calls for other SDK versions.

Setting or behavior	Migration action
Base URL	OpenAI SDK examples include /v1; native Claude / Gemini examples use a root URL and append protocol paths
Credentials	Use a token issued by the target deployment, not the original provider key
Model name	Use the complete deployment ID, including required prefixes; do not assume official aliases exist
Requests and output	Preserve structures within one protocol; update parsing and history together when switching Chat, Responses, Claude, or Gemini
Automatic retries	Identify SDK, application queue, and gateway retry layers and bound total attempts and duplicate work
Extensions	Verify tools, JSON Schema, images, reasoning, store, and other features separately
Implicit resource calls	Check coverage before using Files, Vector Stores, Batch, or Conversations
State and routing	Do not assume stored IDs, compacted ciphertext, signatures, or media tasks migrate across channels

Suggested migration sequence

1. Retain the working configuration and use isolated test settings for the target deployment.
2. Run the quickstart to verify models, URLs, and access.
3. Start with the application’s actual protocol, then test streaming, tools, structured output, and media.
4. Inspect extra resource requests made during framework startup, retrieval, uploads, memory management, and retries.
5. Compare representative inputs for quality, latency, failure behavior, and resource use before shifting limited traffic.

Framework configuration differences

Some clients expect a root URL; others append /v1 or an entire endpoint themselves. Do not copy the SDK URL into every client without checking the final request path. Provider settings in frameworks such as LangChain, LlamaIndex, and AI SDK do not guarantee all features share one Base URL. Consult the installed version’s official documentation and actual requests.

Retries cannot make an absent endpoint available. For conversation memory, start with explicit history; for retrieval, use application-side RAG.

Production acceptance · Troubleshooting

阅读中文

Model routing · Rate limits · Observability · AI SDK