Embedding测试故障排查指南

常见错误及解决方案

1. "对接次数限" 或 API调用限制错误

#### 错误原因

火山方舟API调用次数超过限制
推理接入点配额不足
账户余额不足

#### 解决方案

方案1：检查推理接入点配额

登录火山方舟控制台

进入"推理接入点"管理

查看当前接入点的调用次数和配额

如果配额不足，可以：

- 等待配额重置（通常按天或按月） - 升级推理接入点套餐 - 创建新的推理接入点

方案2：检查账户余额

登录火山方舟控制台

查看账户余额

如果余额不足，充值后重试

方案3：使用其他Embedding服务

临时切换到"腾讯云"模式
或使用"关键词匹配"模式（无需API调用）

2. "请先在'火山方舟'页面配置API密钥"

#### 错误原因

未配置火山方舟API密钥
API密钥配置错误

#### 解决方案

进入"系统配置 > 火山方舟"页面

填写正确的API密钥（API密钥Secret）

点击"保存设置"

返回Embedding配置页面重新测试

3. "请先配置火山方舟Embedding模型"

#### 错误原因

未填写Embedding模型的推理接入点ID
推理接入点ID格式错误

#### 解决方案

登录火山方舟控制台

在模型广场找到"Doubao-embedding-vision"

创建推理接入点

复制推理接入点ID（格式：ep-20260114-xxxxx）

在Embedding配置页面填入ID

保存并重新测试

4. "Embedding测试失败：[错误代码] 错误信息"

#### 常见错误代码

InvalidParameter

原因：参数错误
解决：检查模型ID是否正确

AuthenticationFailed

原因：API密钥认证失败
解决：检查API密钥是否正确

ResourceNotFound

原因：推理接入点不存在
解决：检查推理接入点ID是否正确

RateLimitExceeded

原因：调用频率超限
解决：等待一段时间后重试

InsufficientBalance

原因：账户余额不足
解决：充值后重试

5. 腾讯云Embedding测试失败

#### 错误原因

未配置腾讯云密钥
密钥配置错误
地域选择错误
API调用限制

#### 解决方案

进入"系统配置 > 腾讯云AI"页面

检查SecretId和SecretKey是否正确

确认已启用腾讯云

检查地域选择（推荐：ap-guangzhou）

保存配置后重新测试

6. 网络连接错误

#### 错误信息示例

"Connection timeout"
"Could not resolve host"
"SSL certificate problem"

#### 解决方案

检查服务器网络连接

确认可以访问外网

检查防火墙设置

如果使用代理，配置代理设置

7. 超时错误

#### 错误信息

"Request timeout"
"Operation timed out"

#### 解决方案

检查网络速度

增加超时时间（当前默认30秒）

重试测试

调试技巧

1. 查看详细错误信息

更新后的Embedding配置页面会显示更详细的错误信息，包括：

错误代码
错误描述
请求ID（用于联系技术支持）

2. 查看日志

错误信息会记录在系统日志中：

# 查看日志文件
tail -f writable/logs/log-*.log

3. 使用关键词匹配模式测试

如果API测试一直失败，可以先切换到"关键词匹配"模式：

选择"不使用（关键词匹配）"

保存配置

测试Embedding（应该立即成功）

确认系统功能正常后，再排查API问题

最佳实践

1. 测试前检查清单

[ ] 已配置对应服务商的API密钥
[ ] 模型ID或名称正确
[ ] 账户余额充足
[ ] 网络连接正常
[ ] 推理接入点状态正常

2. 配置建议

生产环境：使用火山方舟或腾讯云
测试环境：可以使用关键词匹配
备用方案：配置多个服务商，互为备份

3. 监控建议

定期检查API调用次数
监控账户余额
设置告警通知

常见问题FAQ

Q1: 测试成功后，实际使用时还是失败？

A: 可能原因：

测试时使用的是临时配置，未保存
配置文件权限问题
缓存问题

解决方法：

确认已点击"保存配置"

检查 writable/config/ai.php 文件权限

清除系统缓存

Q2: 为什么火山方舟测试成功，但腾讯云失败？

A: 两个服务商是独立配置的：

火山方舟需要在"火山方舟"页面配置API密钥
腾讯云需要在"腾讯云AI"页面配置密钥
确保两边都正确配置

Q3: 切换服务商后需要重新索引文档吗？

A: 是的，建议重新索引：

不同服务商的向量维度可能不同

向量化算法不同

重新索引可以获得最佳搜索效果

Q4: 如何查看当前使用的是哪个服务商？

A: 在Embedding配置页面：

点击"查看当前状态"按钮

查看"服务商"和"模型"信息

Q5: 测试文本可以自定义吗？

A: 当前版本使用固定的测试文本。如需自定义：

修改 app/Controllers/Admin/Embedding.php

找到 test() 方法

修改 $testText 变量的值

获取帮助

1. 查看日志

# 查看最新的错误日志
tail -n 100 writable/logs/log-$(date +%Y-%m-%d).log | grep -i "embedding"

2. 联系技术支持

提供以下信息：

错误信息截图
配置信息（隐藏敏感信息）
日志文件相关部分
请求ID（如果有）

3. 社区支持

查看项目文档
搜索类似问题
提交Issue

更新日志

2026-01-21：创建故障排查文档
2026-01-21：改进错误信息显示
2026-01-21：添加详细的错误代码和调试日志