PHP接入AzureAI服务实战教程

本文详细解析了PHP开发者如何通过REST API对接Azure AI核心服务（Text Analytics、Computer Vision和Speech SDK），直击无官方PHP SDK下的实战痛点：认证方式差异（密钥 vs AAD令牌）、请求体结构陷阱（如Text Analytics强制documents数组）、图像上传误区（Computer Vision必须用multipart而非JSON）、Endpoint区域与服务路径的精确匹配要求，以及如何从模糊的400/401错误中快速定位真实原因——所有细节均基于生产环境验证，帮你绕过文档盲区，真正实现稳定调用。

PHP 调用 Azure AI 服务（如 Text Analytics、Computer Vision、Speech SDK 等）本身没有官方 PHP SDK，必须走 REST API；直接用 curl 或 guzzlehttp/guzzle 是唯一稳定路径。

怎么拿到有效的 Azure AI 认证 token？

Azure AI 服务多数使用基于订阅密钥（subscription-key）或 Azure Active Directory（AAD）令牌的认证方式。Text Analytics 和 Computer Vision 当前仍主流用密钥，Speech SDK 则强制要求 AAD token（通过 client_id/client_secret 换取）。

• 密钥方式：在请求头中加 Ocp-Apim-Subscription-Key: ，无需额外 token 获取步骤
• AAD 方式（如 Speech-to-Text）：需先向 https://api.cognitive.microsoft.com/sts/v1.0/issuetoken POST 请求，带 Authorization: Bearer （该 access-token 需先用 Azure AD 应用凭证换取）
• 注意 endpoint 地址格式：不是通用 https://.api.cognitive.microsoft.com 就行，Speech 服务必须用 https://.stt.speech.microsoft.com，写错会返回 404 或 401

用 curl 发起 Text Analytics API 请求时要注意什么？

Text Analytics v3.1（当前稳定版）要求 body 必须是 JSON 数组，且字段名严格为 documents，不能是 texts 或 input；同时每个 document 必须含 id、language、text 三者。

• 错误示例：{"text": "hello"} → 返回 "Invalid request body"
• 正确结构：{"documents": [{"id": "1", "language": "en", "text": "Hello world"}]}
• 别漏设 Content-Type: application/json 和 Ocp-Apim-Subscription-Key 头，否则返回 400 或 401
• region 必须和资源创建时选的一致，比如资源在 westus2，就别用 eastus 的 endpoint，否则报 403 Forbidden

为什么 Guzzle 发送 Computer Vision API 总是 400？

Computer Vision 的 analyze 接口接受两种输入：URL（url 字段）或二进制图像（multipart/form-data）。Guzzle 默认把数组转成 application/json，但图像分析必须用表单提交 —— 这是 400 最常见原因。

• 传图 URL：body 设为 ["url" => "https://..."]，header 保持 Content-Type: application/json
• 传本地图片：必须用 multipart，例如 ['multipart' => [['name' => 'url', 'contents' => file_get_contents($path)]]]，此时 header 不能手动设 Content-Type（Guzzle 会自动生成 boundary）
• 图片大小上限是 4MB，超限返回 "Image size is too large"，别硬扛，先 getimagesize() 校验
• 支持格式有限：仅 jpeg、png、gif、bmp；传 webp 会静默失败（返回空 categories）

真正卡住人的地方，往往不是调不通，而是错误信息太泛（比如一堆 400），而 Azure 的响应体里其实有具体提示字段（如 error.message），建议每次请求后都 var_dump(json_decode($response->getBody(), true)) 看清真实原因。

今天关于《PHP接入AzureAI服务实战教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！