WorkBuddy采用标准OpenAI API协议对接自定义模型，Azure OpenAI服务也兼容此协议，两者通过正确的端点配置即可桥接。 协议兼容机制：WorkBuddy与Azure的握手方式 该平台支持以OpenAI兼容格式接入自定义模型。这意味着任何遵循/v1/chat/completions标准REST路径的推理后端，都可以被系统识别并接管为核心大脑。Azure OpenAI服务的API本质上兼容OpenAI的协议格式，因此WorkBuddy可以直接与其通信，无需额外中间件。这套机制让用户能在桌面智能体工作台中灵活调用企业级模型资源。 参数映射规则：两个关键差异 Azure OpenAI与标准OpenAI API在参数上存在两处关键差异，需要在配置中做适配转换： 鉴权方式：标准OpenAI使用Authorization: Bearer sk-xxx，Azure使用api-key请求头。WorkBuddy的自定义模型配置会自动将API Key字段的值填入api-key头。 部署名称：标准OpenAI将模型名称直接作为model参数；Azure必须在model参数中填写部署名称（Deployment Name），而非模型家族名（如gpt-4），因为部署名称映射到具体的模型版本和容量配额。 配置样例速查 假设你在Azure Portal中创建了以下资源： 资源名称：myworkbuddy 区域：eastus 部署名称：gpt-4-deployment API密钥：abc123xyz 在WorkBuddy中添加自定义模型时填写： API Endpoint：https://myworkbuddy.openai.azure.com/ API Key：abc123xyz 模型ID：gpt-4-deployment 系统的底层通信模块会在实际请求中，自动将上述配置拼装为符合Azure规范的完整URL格式：https://myworkbuddy.openai.azure.com/openai/deployments/gpt-4-deployment/chat/completions?api-version=2024-02-15-preview，并将API Key作为api-key请求头发送。

从零开始完成Azure OpenAI接入WorkBuddy的全链路配置，标准耗时约15-20分钟，核心是获取正确的Endpoint和部署名称。 第一步：在Azure Portal中创建OpenAI资源并获取密钥 登录Azure Portal，在“所有服务”中选择Azure OpenAI服务并创建资源。在基本信息配置中，需要注意以下关键设置：订阅和资源组按企业内部规范选择；区域建议选择离你最近的可用区域（如East US），因为API延迟受区域影响显著；定价层标准为S0。OpenAI资源创建成功后，进入资源详情页，在“资源管理”下的“密钥和端点”中找到API密钥和Endpoint。 需要复制的信息： Endpoint（不含尾部路径） ：https://your-resource-name.openai.azure.com/ API Key：KEY 1或KEY 2均可 接着通过Azure AI Foundry Portal部署模型：从OpenAI资源页点击“Go to Azure AI Foundry Portal”进入部署页面。选择基础模型（如gpt-4、gpt-4o等）并填入部署名称。该名称是WorkBuddy中模型ID的唯一匹配标识，必须记准确。 第二步：在WorkBuddy中添加自定义模型 打开该平台的设置界面，进入左侧导航栏的“模型”→“添加模型”，模型类型选择“OpenAI兼容API”。 关键参数填写如下： 模型名称：填写Azure GPT-4或任意便于识别的名称。 API Endpoint：填写从Azure Portal复制的基础Endpoint，如https://your-resource-name.openai.azure.com/。 API Key：粘贴从Azure Portal复制的密钥。 模型ID：填写步骤一中创建的部署名称（而非模型家族名，如gpt-4-deployment）。 勾选“启用此模型”并点击保存。 第三步：验证配置并开始使用 配置完成后必须完全退出并重启WorkBuddy，因为该应用仅启动时加载自定义模型配置，不重启可能导致模型不可见或调用失败。重启后点击模型切换下拉列表，应能看到新添加的“Azure GPT-4”模型。选中后发送测试指令验证连通性，如“用英文介绍自己”。 验证通过的标准：模型正常返回响应，且无“404”“model not found”“connection timeout”等错误提示。若验证失败，请参考第三篇问题排查指南。

WorkBuddy接入Azure OpenAI失败的主要原因是端点路径错误、部署名称不匹配或网络连通性问题。按以下四类场景逐一排查，90%的问题可在10分钟内解决。 类型一：404错误或“model not found” 这是最常见的接入失败类型，根本原因是WorkBuddy发送请求的URL路径与Azure OpenAI服务的实际路由不匹配。常见错误有三种具体表现：第一，Endpoint错误地包含了/openai/deployments子路径；第二，Endpoint末尾误加了尾部斜杠或查询参数；第三，模型ID填写了GPT-4模型家族名而非部署名称。 解决方案：在Azure Portal中确认资源Endpoint（不含/openai/deployments），并在模型配置中检查模型ID是否与部署名称逐字符一致，包括大小写和连字符。 类型二：401认证失败 触发场景通常为API Key填写错误、Key已过期或该Key关联的订阅余额不足。 解决方案：在Azure Portal中重新生成新的API KEY，更新该平台的API Key字段后再次保存。 类型三：连接超时或拒绝连接 WorkBuddy请求无法到达Azure OpenAI服务，通常由本地防火墙拦截、VPN代理干扰或企业网关策略限制引起。 解决方案：在终端执行curl https://{你的资源名}.openai.azure.com/确认能返回正常响应。若命令执行失败，需检查本地网络或联系IT管理员放行特定域名。 类型四：Base URL格式错误 WorkBuddy对API Endpoint字段进行严格的正则校验，仅接受以http://或https://开头、不含尾部斜杠、不含查询参数的纯地址。 解决方案：确认API Endpoint以https://开头，以基础域结尾且不含尾部斜杠。 最终建议：配置完成后建议重启该智能体工作台。如仍无法解决，可通过WorkBuddy内置的日志导出功能将错误信息发送至技术支持邮箱。