Custom OpenAI Base URL
Change the Host, Verify the Contract自定义 OpenAI 基础地址（Base URL）：更换主机地址，也要验证契约
A base URL redirects your client to a different trust boundary. Treat the host, credentials, data path and compatibility claims as production security and correctness decisions.
基础地址（Base URL）会把客户端重定向到不同信任边界。应把主机地址、凭证、数据路径与兼容声明视为生产安全与正确性决策。
TL;DR
Keep base URL and credentials out of source, screenshots and client bundles.
Require HTTPS, validate certificates and allow only approved hostnames.
Check models, tools, schema, streams, errors and limits before production calls.
Keep provider identity, native IDs, usage and transformations for support and audit.
让基础地址（Base URL）与凭证远离源码、截图与客户端 Bundle。
要求 HTTPS、验证证书，并只允许批准的主机地址name。
生产调用前检查模型、工具、结构定义、流、错误与限制。
保留供应商身份、原生 ID、用量与转换，用于支持与审计。
What changes with base_url更换 base_url 会改变什么
The official OpenAI clients allow the API origin to be configured—base_url in Python and baseURL in JavaScript—but the familiar client method does not guarantee an equivalent service. DNS, TLS certificate and operator, network path, region, credentials, data terms, retention, supported endpoints, streaming event shapes and model behavior can all change behind the new origin.
OpenAI 官方 Client 允许配置 API Origin：Python 使用 base_url，JavaScript 使用 baseURL。但仍能调用熟悉的 Client Method，并不代表背后服务完全等价。新的 Origin 可能改变 DNS、TLS 证书与运营主体、网络路径、区域、凭证、数据条款、保留策略、支持端点、流式事件结构和模型行为。
Treat “OpenAI compatible” as a claim to test endpoint by endpoint. A service may support Chat Completions but not the Responses API, embeddings, files, Batch or every tool option. Even when request fields are accepted, unsupported parameters may be ignored and errors or usage fields may use different semantics.
应把“OpenAI Compatible”视为需要逐端点验证的声明。某项服务可能支持 Chat Completions，却不支持 Responses API、Embedding、Files、Batch 或全部工具选项；即使请求字段被接受，不支持的参数也可能被忽略，错误与用量字段的语义也可能不同。
Promote an approved configuration through development, staging and production. Run a capability preflight and golden contract tests in each environment, then canary one workload at a time. Keep the previous route and credentials ready until the new path proves stable under production-like traffic.
应让批准后的配置依次经过开发、预发和生产环境。在每个环境运行能力预检与 Golden Contract Test，再一次灰度一个工作负载。在新路径通过接近生产的流量验证前，保留旧路由和凭证以便回滚。
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安全推广端点
Test with the same SDK version, timeout, retry settings and transport used in production. A simple text response is only a smoke test; the promotion gate should cover every feature and failure mode the workload relies on.
测试时应使用与生产相同的 SDK 版本、超时、重试设置和传输方式。拿到一次简单文本响应只能算 Smoke Test；推广门禁必须覆盖工作负载依赖的全部功能与故障模式。
- Verify DNS and TLS identity, service operator, region, data terms, retention and credential scope.
- Probe required endpoints and reject silent parameter drops or unexpected redirects.
- Run golden tests for structured output, tools, streaming, usage, errors and request IDs against the current path.
- Canary by workload and tenant while watching latency, retry volume, accounting and output quality.
- Exercise configuration and secret rollback without an application rebuild or client release.
- 验证 DNS 与 TLS 身份、服务运营主体、区域、数据条款、保留策略和凭证范围。
- 探测必需端点，并拒绝参数被静默丢弃或发生意外重定向的路径。
- 针对当前路径运行结构化输出、工具、流式事件、用量、错误和 Request ID 的 Golden Test。
- 按工作负载和租户灰度，同时观测延迟、重试量、核算与输出质量。
- 演练无需重建应用或发布 Client 的配置与 Secret 回滚。
Keep endpoint configuration outside application logic让端点配置远离应用逻辑
The server-side client should resolve an approved endpoint ID to a base URL, scoped credential, expected operator, allowed certificate identity and capability profile. Applications select the endpoint ID or workload alias, not a raw URL. A startup or deployment preflight verifies required endpoints before traffic reaches the new route.
服务端 Client 应把批准的 Endpoint ID 解析为 Base URL、受限凭证、预期运营主体、允许的证书身份和能力 Profile。应用选择的是 Endpoint ID 或工作负载别名，而不是原始 URL。启动或部署预检应在流量进入新路由前验证必需端点。
Requests carry tenant, absolute deadline, trace context and configuration version; responses retain native request IDs, usage and error evidence. Keep HTTP redirects disabled or tightly allowlisted for credential-bearing requests, bound response size and timeouts, and prevent the endpoint from reaching private network ranges. Promote and roll back endpoint configuration separately from application code.
请求应携带租户、绝对截止时间、Trace Context 与配置版本；响应保留原生 Request ID、用量和错误证据。对于携带凭证的请求，应禁用 HTTP Redirect 或只允许严格白名单，同时限制响应大小与超时，并阻止端点访问私有网络地址。端点配置的推广和回滚应与应用代码分开。
Production rule: never accept an arbitrary user-supplied base URL in a privileged server request path; use an allowlisted endpoint registry.
生产规则：绝不能在高权限服务端请求路径中接受任意用户提供的 Base URL；应使用白名单 Endpoint Registry。
Model endpoint configuration is separate from capability discovery模型端点配置与能力发现相互独立
The custom base URL changes how inference is reached. QVeris complements it with governed discovery and execution of external APIs, tools, services and live data. Keep both endpoint registries, credentials, permissions and network policies independently scoped; changing the model origin must not silently redirect tool traffic or broaden capability access.
自定义 Base URL 改变的是推理访问方式；QVeris 补充外部 API、工具、服务与实时数据的治理化发现和执行。两类 Endpoint Registry、凭证、权限和网络策略应分别限制；更换模型 Origin 不能静默重定向工具流量，也不能扩大能力访问范围。
Share a parent trace and configuration snapshot so the complete agent workflow remains explainable. Before using a capability, inspect its schema and provider evidence separately from the model endpoint check. If either side changes, canary that change on its own instead of combining two infrastructure migrations into one release.
双方可共享父 Trace 与配置快照，确保完整 Agent 工作流可解释。使用能力前，应独立检查其 Schema 与 Provider Evidence，而不是把模型端点检查当作工具验证。如果任一侧发生变化，应单独灰度，避免在一次发布中同时进行两项基础设施迁移。
A copy-ready base URL preflight可直接执行的基础地址（Base URL）预检
Run one minimal request before changing application traffic. Keep the endpoint and key in server-side environment variables, pin an exact model ID, and record the provider request ID plus usage fields. A successful response proves reachability only; tool calls, structured output, streaming, timeouts, and error semantics still need separate contract tests.
切换应用流量前，先执行一个最小请求。端点与密钥仅放在服务端环境变量中，固定准确模型 ID，并记录供应商请求 ID 与 Usage 字段。成功响应只能证明连通性；工具调用、结构化输出、流式、超时与错误语义仍需单独做契约测试。
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。
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、数据处理与契约。
不可以。使用可信服务端或网关与受限服务端上游密钥。
不能。测试每个必需功能与故障路径。