Custom OpenAI Base URL
Change the Host, Verify the Contract
自定义 OpenAI 基础地址（Base URL）：更换主机地址，也要验证契约
Changing an OpenAI base URL changes the network operator, credential boundary, data path, supported behavior, and failure semantics—not just the hostname. Prove HTTPS, authentication, exact model access, streaming, structured output, tool calls, errors, usage fields, and rollback before moving production traffic.
更改 OpenAI 基础地址不仅是替换主机名，还会改变网络运营者、凭证边界、数据路径、支持行为与故障语义。迁移生产流量前，应验证 HTTPS、鉴权、准确模型访问、流式、结构化输出、工具调用、错误、用量字段与回滚。
TL;DR
Load the approved URL, exact model ID, and scoped credential from server-side configuration; never accept an arbitrary user-supplied upstream.
Require HTTPS, validate certificates and redirects, allowlist hostnames, and document the operator, region, retention, and support boundary.
Test the exact model, messages, structured output, tools, streams, timeouts, 429s, 5xx responses, usage fields, and provider IDs.
Keep the resolved provider, exact model, native request ID, usage, retries, transformations, and policy result in one trace.
从服务端配置加载批准的 URL、准确模型 ID 与受限凭证；绝不接受用户任意提供的上游地址。
要求 HTTPS，验证证书与重定向，只允许批准的主机名，并记录运营者、区域、留存与支持边界。
测试准确模型、消息、结构化输出、工具、流式、超时、429、5xx、用量字段与供应商 ID。
在同一追踪中保留解析后的供应商、准确模型、原生请求 ID、用量、重试、转换与策略结果。
What changes with base_url 更换 base_url 会改变什么
The SDK request shape may stay familiar, but DNS, TLS, operator, region, credentials, data terms, retention, supported endpoints and model behavior can all change.
SDK 请求形状可能保持熟悉，但 DNS、TLS、运营者、区域、凭证、数据条款、保留、支持端点与模型行为都可能变化。
Promote configuration through development, staging and production. Contract-test the endpoint and keep the previous route ready until the new path proves stable.
通过开发、预发与生产逐级推广配置。契约测试端点，并在新路径证明稳定前保留旧路由。
Configuration layers to verify 需要验证的配置层
| Layer 层 | Best fit 最适合 | Verify before choosing 选择前验证 |
|---|---|---|
| Host and TLS 主机地址与 TLS | Approved HTTPS endpoint with valid certificate chain. 批准的 HTTPS 端点与有效证书链。 | Protect against redirects, unexpected hosts and proxy interception. 防止重定向、意外主机地址与代理拦截。 |
| Credentials 凭证 | Server-side, scoped, rotated and environment-specific keys. 服务端、受限、轮换且环境特定的密钥。 | Never reuse broad production secrets in local or client code. 不得在本地或客户端代码复用宽泛生产密钥。 |
| Compatibility 兼容性 | Required paths, fields, tools, streams, errors and usage. 所需路径、字段、工具、流、错误与用量。 | Test semantics; a successful simple chat call is insufficient. 测试语义；一次简单 Chat 成功远远不够。 |
| Operations 运营 | Timeouts, retries, logs, data handling and rollback. 超时、重试、日志、数据处理与回滚。 | Assign retry ownership and retain native identity. 指定重试归属并保留原生身份。 |
Secure setup checklist 安全设置检查清单
Load keys from an approved secret store and scope them to needed models.
Validate scheme, hostname, port and optional network range.
Cover chat, tools, structured output, streams, errors and cancellation.
Version configuration and keep a known-good endpoint ready.
从批准上游密钥 Store 加载密钥，并限制到所需模型。
验证 Scheme、主机地址name、Port 与可选网络范围。
覆盖 Chat、工具、结构化输出、流、错误与取消。
版本化配置，并准备已知可用端点。
Promote the endpoint safely 安全推广端点
- Verify TLS, operator, region, data terms and credentials.
- Run golden contract tests and compare against the current path.
- Canary by workload while watching errors, usage and output quality.
- Exercise configuration rollback without an application rebuild.
- 验证 TLS、运营者、区域、数据条款与凭证。
- 运行 Golden 契约测试并与当前路径比较。
- 按负载灰度，并观测错误、用量与输出质量。
- 演练无需重建应用的配置回滚。
Keep endpoint configuration outside application logic 让端点配置远离应用逻辑
The server-side client reads an approved base URL and scoped key from the environment. A preflight verifies required capabilities. Requests carry tenant and trace context; responses keep native IDs and usage. Configuration promotion and rollback are versioned separately from application code.
服务端客户端从环境读取批准基础地址（Base URL）与受限密钥；预检验证必需能力；请求携带租户与调用链上下文，响应保留原生 ID 与用量。配置推广与回滚独立于应用代码版本化。
Production rule: never accept an arbitrary user-supplied base URL in a privileged server request path.
生产规则：绝不能在高权限服务端请求路径中接受任意用户提供的基础地址（Base URL）。
Model endpoint configuration is separate from capability discovery 模型端点配置与能力发现相互独立
Treat the model base URL and the QVeris capability endpoint as separate trust boundaries. Give each an independent allowlist, credential, timeout, retry budget, audit record, and rollback switch. Share only workflow, tenant, and trace context so a model-provider outage cannot silently redirect or replay a side-effecting tool call.
模型基础地址与 QVeris 能力端点是两个独立信任边界。它们应分别拥有允许列表、凭证、超时、重试预算、审计记录与回滚开关，只共享工作流、租户和追踪上下文，避免模型供应商故障静默重定向或重复执行有副作用的工具调用。
A copy-ready base URL preflight 可直接执行的基础地址（Base URL）预检
Run the existing minimal request before changing traffic, but interpret it narrowly: a successful response proves DNS, TLS, authentication, path joining, and one model call. Record the exact SDK and model versions, native request ID, resolved provider, latency, and usage fields. Then run separate fixtures for streaming event order, JSON Schema enforcement, tool-call arguments, cancellation, timeout, 429, 5xx, and malformed responses.
切换流量前先运行现有最小请求，但要严格限定结论：成功响应只证明 DNS、TLS、鉴权、路径拼接和一次模型调用。记录准确 SDK 与模型版本、原生请求 ID、解析后的供应商、延迟和用量字段，再分别运行流式事件顺序、JSON Schema 约束、工具参数、取消、超时、429、5xx 与畸形响应 Fixture。
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["LLM_API_KEY"],
base_url=os.environ["LLM_BASE_URL"].rstrip("/") + "/",
timeout=20.0,
max_retries=0,
)
response = client.chat.completions.create(
model=os.environ["LLM_MODEL_ID"],
messages=[{"role": "user", "content": "Reply with BASE_URL_OK"}],
max_completion_tokens=16,
)
print(response.id, response.choices[0].message.content, response.usage)
- Reject non-HTTPS production URLs and unexpected redirects.
- Test authentication, model-not-found, timeout, 429, and 5xx responses separately.
- Canary the new endpoint, then retain a one-command rollback to the previous URL.
- 生产环境拒绝非 HTTPS URL 与意外重定向。
- 分别测试认证失败、模型不存在、超时、429 与 5xx。
- 对新端点做灰度，并保留一条命令即可回滚的旧 URL。
Verified implementation reference: OpenAI Python library.
实施参考已根据官方资料核验：OpenAI Python library。
Define the Production Contract for an OpenAI base URL change定义OpenAI 基础地址变更的生产契约
An OpenAI-compatible hostname can accept the same SDK call while changing path joining, authentication headers, model IDs, stream events, tool arguments, usage accounting, error bodies, and retry behavior. Treat the base URL configuration as a versioned production contract with an owner and rollback target.
OpenAI 兼容主机即使接受同一 SDK 调用，也可能改变路径拼接、鉴权请求头、模型 ID、流式事件、工具参数、用量核算、错误体与重试行为。应把基础地址配置视为有负责人和回滚目标的版本化生产契约。
Record whether the configured value includes /v1, how the SDK joins paths, whether redirects are allowed, which certificate chain and hostname are expected, which authentication and organization headers pass through, and which exact model-list, chat, Responses, streaming, and health endpoints exist.
记录配置值是否包含 /v1、SDK 如何拼接路径、是否允许重定向、预期证书链与主机名、哪些鉴权和组织请求头会透传，以及准确存在的模型列表、Chat、Responses、流式与健康检查端点。
Run the same SDK against the old and new base URLs with fixtures for Unicode, long context, JSON Schema, parallel tools, streaming order, cancellation, invalid authentication, unknown model, malformed input, 429, timeout, and 5xx. Diff structured fields and event order, not only final text.
使用同一 SDK 分别请求旧、新基础地址，运行 Unicode、长上下文、JSON Schema、并行工具、流式顺序、取消、无效鉴权、未知模型、畸形输入、429、超时与 5xx Fixture。比较结构化字段与事件顺序，而不只比较最终文本。
For every base-URL request, keep the configuration version, internal trace ID, native request ID, resolved operator and model, request transformation, attempt count, timeout source, latency, token classes, usage and cost source, status code, and validation result. Redact the key while preserving reproducible context.
每次基础地址请求都应保留配置版本、内部追踪 ID、原生请求 ID、解析后的运营者与模型、请求转换、尝试次数、超时来源、延迟、Token 类别、用量与成本来源、状态码和校验结果。脱敏密钥时仍要保留可复现上下文。
Promote the new base URL through versioned environment configuration, shadow read-only traffic, and canary workloads without side effects. Compare completion, schema validity, tool accuracy, p95 latency, 429/5xx rates, and usage reconciliation; retain the previous URL and credential until one-command rollback and return-to-primary both pass.
通过版本化环境配置推广新基础地址，先运行只读影子流量，再灰度无副作用工作负载。比较完成率、结构有效性、工具准确率、p95 延迟、429/5xx 比例与用量对账；在一键回滚和恢复主路径均通过前，保留旧 URL 与凭证。
FAQ
It can be, after the operator, TLS, data handling and contract are verified.
No. Use a trusted server or gateway and scoped server-side secrets.
No. Test each required feature and failure path.
可以，但需验证运营者、TLS、数据处理与契约。
不可以。使用可信服务端或网关与受限服务端上游密钥。
不能。测试每个必需功能与故障路径。