Embedding测试故障排查
==============================

作者: 系统管理员
更新时间: 2026-03-24 04:38:15

----------------------------------------

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调用次数
监控账户余额
设置告警通知

常见问题FAQQ1: 测试成功后，实际使用时还是失败？
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：添加详细的错误代码和调试日志