只需替换api key、base_url和model三处配置即可无缝切换：将openai客户端的api_key和base_url设为混元对应值（https://api.hunyuan.cloud.tencent.com/v1），再将model参数改为hunyuan-turbos-latest等实际支持的模型名。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你正在维护一个用OpenAI Python SDK写的项目，现在想把后端模型从OpenAI切换成腾讯混元，但又不想重写全部调用逻辑——只需改3处关键配置就能跑通。
确认SDK版本与兼容性前提
确保你当前项目使用的是 openai>=1.0.0 的新版SDK（非旧版 openai==0.28.x）。旧版SDK不支持 base_url 参数，强行替换会导致 ConnectionError 或 404 错误。
运行 pip show openai 查看版本；若低于 1.0.0，请先执行 pip install --upgrade openai。
替换三处核心参数
找到你初始化 OpenAI 客户端的代码位置（通常在 config.py、llm.py 或 main.py 开头），将原始写法：
client = OpenAI(api_key="sk-xxx")
替换成以下任一方式：
方法一：直接传参（推荐）
client = OpenAI(<br> api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",<br> base_url="https://api.hunyuan.cloud.tencent.com/v1"<br>)
注意：base_url 必须以 /v1 结尾，少这个路径会导致 404；混元不接受 /v1/ 后多加斜杠。
方法二：环境变量注入（适合部署）
在启动前设置两个环境变量：
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx<br>OPENAI_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
然后代码中只需写
client = OpenAI() 即可自动读取。
方法三：全局配置（慎用）
在项目任意早期加载位置插入：
import openai<br>openai.api_key = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"<br>openai.base_url = "https://api.hunyuan.cloud.tencent.com/v1"
⚠️ 这种写法会污染全局状态，若项目中同时调用其他兼容接口（如百炼、千帆），极易引发冲突。
调整 model 参数并验证响应结构
第一步：把原来调用的模型名（如 gpt-3.5-turbo）换成混元实际支持的模型名，例如：
→ hunyuan-turbos-latest（通用对话）
→ hunyuan-pro（长文本强推理）
→ hunyuan-vision（多模态图生文）
→ hunyuan-ocr（纯OCR专用，仅支持 /v1/ocr 接口，不走 chat.completions）
第二步：发送最简测试请求，验证基础通路是否打通：
response = client.chat.completions.create(<br> model="hunyuan-turbos-latest",<br> messages=[{"role": "user", "content": "你好"}]<br>)<br>print(response.choices[0].message.content)
第三步：检查返回字段。混元兼容 OpenAI 接口，但 不返回 usage 字段中的 prompt_tokens 和 completion_tokens（除非显式开启 enable_enhancement 等扩展参数），若你的代码依赖这些字段做计费统计，需提前兜底处理空值。
处理流式响应（stream=True）
如果你原项目启用了流式输出（stream=True），混元完全支持，但注意：
→ 响应 chunk 中的 delta.content 可能为 None（尤其在首 chunk 出现 role 字段时），务必加 if chunk.delta.content 判断再打印；
→ 混元默认不返回 finish_reason 字段，若业务逻辑强依赖该字段判断结束，需监听 chunk.choices[0].finish_reason 是否存在，不存在则视为未结束。
调试失败时优先检查这三项
① 请求地址是否拼错：必须是 https://api.hunyuan.cloud.tencent.com/v1，不是 hunyuan.tencentcloudapi.com 或其他变体；
② API KEY 是否已开通混元服务权限：登录腾讯云控制台 → 访问管理 → API密钥管理 → 查看该密钥是否已授权「Hunyuan」服务；
③ 模型名称是否在混元控制台「模型广场」中显示为「已开通」状态——未开通的模型即使名称正确也会返回 403 Forbidden。
