1. 前置检查
1）确认大模型及其参数、并发能力，满足 推荐大模型 要求。
2）确认完成 连接测试：
2. 常见问题
2.1 连接测试失败
1）若FineAI 插件和 FineBI 平台互通测试失败
答：按 F12 打开浏览器开发者工具，查看 test 请求响应中的 error_message 字段，可以判断是 BI 连不上 FineAI，还是 FineAI 连不上 BI。
2）若大模型连接测试失败
答：通过 F12 查看请求响应中的 error_message，定位具体原因。
2.2 Dora 无法正常响应，请求超时或无返回
原因：
网络通信问题
检查步骤：
1）检查 FineAI 节点是否正常运行
FineAI 可直接联通大模型，BI-Web 需与 FineAI 双向通信，可点击连接测试验证联通情况。
2）连接测试不通时，通过 F12 查看 error_message，判断断链位置。
2.3 第一个请求报错，第二个请求正常
原因：
Dora 必须依赖 tool_call，当前大模型不支持
检查步骤：
进入部署 FineAI 的服务器，用以下两条 curl 命令测试（请替换 URL、apikey 和模型名），若第一条报错而第二条正常，说明当前使用模型不支持 tool_call，需更换模型。
| 第一条（带 tool_call，不支持时会报错） |
curl -X POST 'http://<your-model-endpoint>/v1/chat/completions' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-apikey>' \
-d '{
"model": "<your-model-name>",
"messages": [{"role": "user", "content": "Hello!"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": ""}},
"required": ["city"]
}
}
}],
"tool_choice": "auto",
"stream": false
}'
|
| 第二条（不带 tool_call，正常返回） |
curl -X POST 'http://<your-model-endpoint>/v1/chat/completions' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <your-apikey>' \
-d '{
"model": "<your-model-name>",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": false
}'
|
2.4 请求返回 422 状态码
原因：
部署的大模型可能不符合 OpenAI 接口协议规范。
检查步骤：
提供接口日志，联系帆软介入排查。
2.5 请求中 system content 相关字段报错
原因：
部分大模型只支持 system content 为 string 类型，不支持其他格式
检查步骤：
确认目前使用的大模型是否对 system content 格式有限制，如有则需调整请求格式。
2.6 使用 Azure OpenAI 时连接测试不通
原因：
Azure 暂不支持 responses API 格式的 endpoint。
解决方式：
将 endpoint 改为 base URL 格式即可联通。
2.7 返回 ai-server-error 错误
原因：
大模型上下文长度不足 128k
排查步骤：
确认模型上下文长度是否满足 128K 最低要求。
2.8 Azure 模型响应内容异常或中断
原因：
Azure 模型自带内容安全拒识机制，当触发关键词时会中断响应。
排查步骤：
更换提问，避免触发拒识关键词。
2.9 模型调用失败，提示无法访问
原因：
模型服务压力过大，暂时无法响应。
排查步骤：
稍后再试。可参考 推荐大模型 中的并发与性能参考，评估模型负载情况。
2.10 模型调用返回欠费相关错误
原因：
模型欠费
解决方式：
充值后恢复使用
2.11 OpenAI 参数错误
问题现象：
报错 Error code: 422 - {'error': 'Check open ai req parameter error', 'error_type': 'Input Validation Error'}
检查步骤：
进入部署 FineAI 的服务器，通过以下两条 curl 命令测试，若第一个条报错，第二条正常，说明 OpenAI 协议兼容层：接口不支持 messages.content 的 content block 数组格式（即："content": [{"type": "text", "text": "..."}]），只支持字符串格式（即： "content": "..."）。
| 第一条crul命令 |
curl -X POST '<客户base_url>/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <客户API_KEY>' \
-d '{
"model": "<客户模型名>",
"stream": true,
"stream_options": {
"include_usage": true
},
"messages": [
{
"role": "system",
"content": [
{
"type": "text",
"text": "You are llm-test. You are a helpful assistant."
}
]
},
{
"role": "user",
"content": "请测试工具调用能力。本轮是连接测试 dry-run，不会执行工具。请不要输出自然语言，请仅调用工具 llm_connectivity_probe，并传入 JSON 参数 {\"probe_text\":\"ok\"}。"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "llm_connectivity_probe",
"description": "Confirm that the model can emit a valid OpenAI tool call with JSON arguments.",
"parameters": {
"type": "object",
"properties": {
"probe_text": {
"type": "string"
}
},
"required": [
"probe_text"
]
}
}
}
]
}'
|
| 第二条crul命令 |
curl -X POST '<客户base_url>/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <客户API_KEY>' \
-d '{
"model": "<客户模型名>",
"stream": true,
"stream_options": {
"include_usage": true
},
"messages": [
{
"role": "system",
"content": "You are llm-test. You are a helpful assistant."
},
{
"role": "user",
"content": "请测试工具调用能力。本轮是连接测试 dry-run，不会执行工具。请不要输出自然语言，请仅调用工具 llm_connectivity_probe，并传入 JSON 参数 {\"probe_text\":\"ok\"}。"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "llm_connectivity_probe",
"description": "Confirm that the model can emit a valid OpenAI tool call with JSON arguments.",
"parameters": {
"type": "object",
"properties": {
"probe_text": {
"type": "string"
}
},
"required": [
"probe_text"
]
}
}
}
]
}'
|
解决方式：
方式一：调整模型，使其支持 content: [{type:"text", text:"..."}]
方式二：直接更换到支持 content: [{type:"text", text:"..."}] 的模型
上一篇：常见问题排查