Embedding测试故障排查

# Embedding测试故障排查指南 ## 常见错误及解决方案 ### 1. "对接次数限" 或 API调用限制错误 #### 错误原因 - 火山方舟API调用次数超过限制 - 推理接入点配额不足 - 账户余额不足 #### 解决方案 **方案1：检查推理接入点配额** 1. 登录火山方舟控制台 2. 进入"推理接入点"管理 3. 查看当前接入点的调用次数和配额 4. 如果配额不足，可以： - 等待配额重置（通常按天或按月） - 升级推理接入点套餐 - 创建新的推理接入点 **方案2：检查账户余额** 1. 登录火山方舟控制台 2. 查看账户余额 3. 如果余额不足，充值后重试 **方案3：使用其他Embedding服务** - 临时切换到"腾讯云"模式 - 或使用"关键词匹配"模式（无需API调用） ### 2. "请先在'火山方舟'页面配置API密钥" #### 错误原因 - 未配置火山方舟API密钥 - API密钥配置错误 #### 解决方案 1. 进入"系统配置 > 火山方舟"页面 2. 填写正确的API密钥（API密钥Secret） 3. 点击"保存设置" 4. 返回Embedding配置页面重新测试 ### 3. "请先配置火山方舟Embedding模型" #### 错误原因 - 未填写Embedding模型的推理接入点ID - 推理接入点ID格式错误 #### 解决方案 1. 登录火山方舟控制台 2. 在模型广场找到"Doubao-embedding-vision" 3. 创建推理接入点 4. 复制推理接入点ID（格式：ep-20260114-xxxxx） 5. 在Embedding配置页面填入ID 6. 保存并重新测试 ### 4. "Embedding测试失败：[错误代码] 错误信息" #### 常见错误代码 **InvalidParameter** - 原因：参数错误 - 解决：检查模型ID是否正确 **AuthenticationFailed** - 原因：API密钥认证失败 - 解决：检查API密钥是否正确 **ResourceNotFound** - 原因：推理接入点不存在 - 解决：检查推理接入点ID是否正确 **RateLimitExceeded** - 原因：调用频率超限 - 解决：等待一段时间后重试 **InsufficientBalance** - 原因：账户余额不足 - 解决：充值后重试 ### 5. 腾讯云Embedding测试失败 #### 错误原因 - 未配置腾讯云密钥 - 密钥配置错误 - 地域选择错误 - API调用限制 #### 解决方案 1. 进入"系统配置 > 腾讯云AI"页面 2. 检查SecretId和SecretKey是否正确 3. 确认已启用腾讯云 4. 检查地域选择（推荐：ap-guangzhou） 5. 保存配置后重新测试 ### 6. 网络连接错误 #### 错误信息示例 - "Connection timeout" - "Could not resolve host" - "SSL certificate problem" #### 解决方案 1. 检查服务器网络连接 2. 确认可以访问外网 3. 检查防火墙设置 4. 如果使用代理，配置代理设置 ### 7. 超时错误 #### 错误信息 - "Request timeout" - "Operation timed out" #### 解决方案 1. 检查网络速度 2. 增加超时时间（当前默认30秒） 3. 重试测试 ## 调试技巧 ### 1. 查看详细错误信息 更新后的Embedding配置页面会显示更详细的错误信息，包括： - 错误代码 - 错误描述 - 请求ID（用于联系技术支持） ### 2. 查看日志 错误信息会记录在系统日志中： ```bash # 查看日志文件 tail -f writable/logs/log-*.log ``` ### 3. 使用关键词匹配模式测试 如果API测试一直失败，可以先切换到"关键词匹配"模式： 1. 选择"不使用（关键词匹配）" 2. 保存配置 3. 测试Embedding（应该立即成功） 4. 确认系统功能正常后，再排查API问题 ## 最佳实践 ### 1. 测试前检查清单 - [ ] 已配置对应服务商的API密钥 - [ ] 模型ID或名称正确 - [ ] 账户余额充足 - [ ] 网络连接正常 - [ ] 推理接入点状态正常 ### 2. 配置建议 - 生产环境：使用火山方舟或腾讯云 - 测试环境：可以使用关键词匹配 - 备用方案：配置多个服务商，互为备份 ### 3. 监控建议 - 定期检查API调用次数 - 监控账户余额 - 设置告警通知 ## 常见问题FAQ ### Q1: 测试成功后，实际使用时还是失败？ A: 可能原因： - 测试时使用的是临时配置，未保存 - 配置文件权限问题 - 缓存问题 解决方法： 1. 确认已点击"保存配置" 2. 检查 `writable/config/ai.php` 文件权限 3. 清除系统缓存 ### Q2: 为什么火山方舟测试成功，但腾讯云失败？ A: 两个服务商是独立配置的： - 火山方舟需要在"火山方舟"页面配置API密钥 - 腾讯云需要在"腾讯云AI"页面配置密钥 - 确保两边都正确配置 ### Q3: 切换服务商后需要重新索引文档吗？ A: 是的，建议重新索引： 1. 不同服务商的向量维度可能不同 2. 向量化算法不同 3. 重新索引可以获得最佳搜索效果 ### Q4: 如何查看当前使用的是哪个服务商？ A: 在Embedding配置页面： 1. 点击"查看当前状态"按钮 2. 查看"服务商"和"模型"信息 ### Q5: 测试文本可以自定义吗？ A: 当前版本使用固定的测试文本。如需自定义： 1. 修改 `app/Controllers/Admin/Embedding.php` 2. 找到 `test()` 方法 3. 修改 `$testText` 变量的值 ## 获取帮助 ### 1. 查看日志 ```bash # 查看最新的错误日志 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：添加详细的错误代码和调试日志