AI Search 常见陷阱

# AI Search 常见陷阱 ## 类型安全 **时间戳精度：** 使用秒（10 位），而非毫秒。 typescript const nowInSeconds = Math.floor(Date.now() / 1000); // 正确 **文件夹前缀匹配：** 在路径上使用 `gte` 表示“以...开头”。 typescript filters: { column: "folder", operator: "gte", value: "docs/api/" } // 匹配嵌套路径 ## 过滤器限制 | 限制 | 值 | |-------|-------| | 最大嵌套深度 | 2 层 | | 每个复合过滤器的过滤器数 | 10 | | `or` 运算符 | 仅限相同列，仅限 `eq` | **OR 限制示例：** typescript // ✅ 有效：相同列，仅限 eq { operator: "or", filters: [ { column: "folder", operator: "eq", value: "docs/" }, { column: "folder", operator: "eq", value: "guides/" } ]} ## 索引问题 | 问题 | 原因 | 解决方案 | |---------|-------|----------| | 文件未索引 | 格式不支持或 >4MB | 检查格式 (.md/.txt/.html/.pdf/.doc/.csv/.json) | | 索引不同步 | 6 小时索引周期 | 等待或使用“强制同步”（30 秒速率限制） | | 结果为空 | 索引不完整 | 在仪表板检查索引状态 | ## 认证错误 | 错误 | 原因 | 修复 | |-------|-------|-----| | `AutoRAGUnauthorizedError` | 令牌无效/缺失 | 创建具有 AI Search 权限的服务 API 令牌 | | `AutoRAGNotFoundError` | 实例名称错误 | 从仪表板验证确切名称 | ## 性能 **响应缓慢 (>3s)：** typescript // 添加分数阈值 + 限制结果数 ranking_options: { score_threshold: 0.5 }, max_num_results: 10 **结果为空调试：** 1. 移除过滤器，测试基本查询 2. 将 `score_threshold` 降低至 0.1 3. 检查索引是否已填充 ## 限制 | 资源 | 限制 | |----------|-------| | 每个账户的实例数 | 10 | | 每个实例的文件数 | 100,000 | | 最大文件大小 | 4 MB | | 索引频率 | 6 小时 | ## 反模式 **使用环境变量作为实例名称：** typescript const answer = await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({...}); **处理特定错误类型：** typescript if (error instanceof AutoRAGNotFoundError) { /* 404 */ } if (error instanceof AutoRAGUnauthorizedError) { /* 401 */ }