workbuddy自定义大模型接入失败主因是模型服务未严格遵循openai兼容接口规范，需依次验证api端点路径、响应头字段、base url格式、模型id一致性，并启用调试日志定位协议偏差。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在WorkBuddy中配置自定义大模型后无法成功接入，且反复出现连接失败、404错误或“model not found”提示，则很可能是模型服务未严格遵循OpenAI兼容接口规范。以下是排查与修复该问题的步骤：
一、验证API端点是否符合OpenAI v1标准路径
WorkBuddy默认调用OpenAI兼容接口，要求模型服务必须暴露标准REST路径，任何路径偏差都会导致路由失败。非标准路径（如/v1/chat、/api/chat/completions）将被直接拒绝。
1、检查模型服务启动时监听的完整URL，确认其以/v1/chat/completions结尾，例如http://127.0.0.1:8000/v1/chat/completions。
2、使用curl命令发起最小化请求，明确指定Content-Type和JSON结构：
curl -X POST http://127.0.0.1:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"test","messages":[{"role":"user","content":"test"}]}'
3、观察响应体是否包含choices数组及其中的message.content字段；若返回{"error": "Not Found"}或空响应，则说明端点未正确注册。
二、检查HTTP响应头是否携带必需字段
WorkBuddy在初始化阶段会预检模型服务的响应头，若缺失X-Model-ID或Content-Type: application/json，将中断加载流程并静默失败。
1、在终端执行带-I参数的curl命令获取响应头：
curl -I http://127.0.0.1:8000/v1/models
2、确认输出中存在Content-Type: application/json，且无text/html或text/plain等错误类型。
3、若使用vLLM部署，需在启动命令中添加--lora-modules以外的显式头注入参数；若使用FastAPI，须在response对象中手动设置headers={"X-Model-ID": "deepseek-coder-1.3b-base"}。
三、校验模型配置中的Base URL格式合法性
WorkBuddy对Base URL执行严格正则校验，仅接受以http://或https://开头、不含路径片段（除/v1外）、不带查询参数的纯地址。任意多余字符都将触发解析异常。
1、打开WorkBuddy设置→AI模型→自定义模型编辑页，定位“API基础地址”字段。
2、确认填写内容为http://127.0.0.1:8000/v1或https://api.example.com/v1，严禁包含末尾斜杠、/chat/completions子路径、?token=xxx等查询参数。
3、若地址含中文、空格或Unicode字符，需先进行URL编码；例如http://本地主机:8000/v1必须改为http://%E6%9C%AC%E5%9C%B0%E4%B8%BB%E6%9C%BA:8000/v1。
四、确认模型ID与服务实际声明完全一致
WorkBuddy将模型ID作为路由键传递至后端，若与推理服务返回的model字段值不匹配（包括大小写、连字符、版本后缀），将返回404而非500错误，极易误判为网络问题。
1、向/v1/models端点发送GET请求，解析返回JSON中的data[0].id字段值，例如"deepseek-coder-1.3b-base"。
2、进入WorkBuddy模型配置页，在“模型ID”输入框中**逐字符比对粘贴**该值，禁止删减"-base"、误写为"1.3b"或大小写混用。
3、若服务返回多个模型，需确保WorkBuddy中填写的ID精确对应目标模型，不可填写列表名称或别名。
五、启用调试日志捕获底层协议错误
WorkBuddy内置HTTP客户端调试模式，可输出原始请求/响应体及状态码，用于识别OpenAI协议层面的细微偏差，如字段命名错误、嵌套层级错位等。
1、关闭WorkBuddy主程序，在终端中设置环境变量：
Windows：set WORKBUDDY_DEBUG_HTTP=1
macOS/Linux：export WORKBUDDY_DEBUG_HTTP=1
2、重新启动WorkBuddy，复现接入失败操作。
3、查看控制台输出，定位首条REQUEST:与紧随其后的RESPONSE STATUS:行，若状态码为200但响应体缺少choices或message，则判定为协议结构不兼容。
