要在ThinkPHP项目中调用DeepSeek-V3或OpenAI等支持OpenAI协议的大模型API，必须将请求参数、路径、认证方式严格对齐OpenAI v1标准，否则会返回401或404错误。
确认API端点与协议版本
所有兼容请求必须使用 https://api.deepseek.com/v1/chat/completions 或你部署的OpenAI兼容服务地址（如中转代理、本地Ollama），不能用/v3、/v2等非标准路径。官方DeepSeek-V3虽支持/v3原生接口，但OpenAI兼容模式只响应/v1前缀。
检查你拿到的文档或控制台说明——若写明“OpenAI兼容”或“openai_compat=true”，就只能走/v1；若只写“v3 API”，默认不兼容，需额外启用兼容开关。
配置HTTP请求头：Authorization与Content-Type
在ThinkPHP控制器中构造Guzzle Client时，必须设置两个关键Header：
Authorization: Bearer 【your_api_key】
Content-Type: application/json
注意：Bearer后必须有且仅有一个空格，key值不能带引号，也不能拼错成“bear”或“breaer”。密钥泄露风险极高，【绝对不可硬编码在控制器里】，应从环境变量读取：$_ENV['DEEPSEEK_API_KEY'] 或 Config::get('api.deepseek.key')。
构造messages数组：角色顺序与必填字段
OpenAI协议要求messages为对象数组，每个元素含role和content字段，且至少包含一个user消息。
role只能是"system"、"user"、"assistant"三者之一，大小写敏感，不能写成"User"或"SYSTEM"。
system消息可选，但若存在，必须放在数组最前面；user消息必须存在，且不能为空字符串；assistant消息仅用于历史对话续写，首次请求通常不填。
示例合法结构：
[{"role":"system","content":"你用中文回答"},{"role":"user","content":"你好"}]
设置核心参数：model、temperature、max_tokens
model字段必须填写服务端实际支持的模型标识符，例如"deepseek-v3"、"gpt-4-turbo"或"llama-3-70b"。该值区分大小写，且不能多出空格。
temperature取值范围为0.0～2.0，默认0.7；设为0会禁用随机性，适合确定性任务如代码生成。
max_tokens表示最大输出长度，不是总上下文长度。若输入已占2000 tokens，而你设max_tokens=500，总消耗即为2500 tokens。
处理流式响应（Streaming）
方法一：启用SSE推送（推荐用于前端实时打字效果）
在ThinkPHP控制器中设置header('Content-Type: text/event-stream'); 并在Guzzle请求中开启stream => true选项；每次收到data: {...}块后立即echo并调用ob_flush()和flush()。
方法二：普通JSON响应（适合简单问答）
直接接收完整响应体，用json_decode($response->getBody(), true)解析；注意检查response['choices'][0]['message']['content']是否存在，部分错误响应无该字段。
注意：流式响应下，Guzzle默认会缓存整个body，必须显式设置stream => true + sink => fopen('php://output', 'w')才能边收边发。
错误排查关键点
第一步：用curl命令行验证基础连通性
curl -X POST "https://api.deepseek.com/v1/chat/completions" -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" -d '{"model":"deepseek-v3","messages":[{"role":"user","content":"test"}]}'
第二步：若返回401，检查密钥是否过期、IP是否被拦截、header拼写是否错误。
第三步：若返回400且提示"invalid request"，逐项核对messages格式、model值、JSON语法是否合法（尤其引号是否为英文、逗号是否多余）。
第四步：若返回500或超时，确认网络能否直连api.deepseek.com（国内服务器常需代理）。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
