docs: 添加 AI 智能搜索系统设计文档

2026-01-25 17:20:02 +08:00
parent f0aa0616f7
commit dbbe481be7
1 changed files with 502 additions and 0 deletions
@@ -0,0 +1,502 @@
+# AI 智能搜索系统设计文档
+
+**日期**: 2026-01-25
+**作者**: Claude Code
+**状态**: 设计阶段
+
+## 概述
+
+为项目列表添加 AI 语义搜索功能，用户可通过自然语言描述需求，系统通过向量相似度匹配返回相关项目，而非传统的关键词模糊搜索。
+
+### 核心目标
+
+- ✅ 支持自然语言查询（如"帮我找做图像生成的项目"）
+- ✅ 基于向量相似度的语义匹配
+- ✅ 完全在 n8n 中实现 AI 逻辑，Next.js 应用保持纯净
+- ✅ 利用现有 Neon 数据库的 pgvector 扩展
+
+---
+
+## 架构设计
+
+### 整体架构
+
+```
+前端（Next.js）
+    ↓
+API 代理（/api/search/ai）
+    ↓
+n8n 工作流（AI 逻辑）
+    ↓
+Neon 数据库（pgvector）
+```
+
+### 核心组件
+
+**数据层（Neon + pgvector）**
+- `Project` 表添加 `embedding` 字段存储向量
+- HNSW 索引加速相似度搜索
+- 向量维度：1536（OpenAI text-embedding-3-small）
+
+**服务层（n8n 工作流）**
+- **向量化工作流**：定时扫描未向量化项目，调用 OpenAI API 生成向量
+- **AI 搜索工作流**：接收查询 → 生成向量 → 相似度搜索 → 返回结果
+
+**前端层（Next.js）**
+- 搜索框增加 AI 模式切换按钮
+- 显示相似度评分和匹配原因
+
+---
+
+## 数据库设计
+
+### Schema 修改
+
+```prisma
+model Project {
+  // ... 现有字段
+
+  // 新增：向量嵌入字段
+  embedding          vector(1536)?   // pgvector 类型
+  embeddingUpdatedAt DateTime?       // 向量化更新时间
+}
+```
+
+### 迁移 SQL
+
+```sql
+-- 启用 pgvector 扩展
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- 添加向量列
+ALTER TABLE "Project" ADD COLUMN "embedding" vector(1536);
+ALTER TABLE "Project" ADD COLUMN "embeddingUpdatedAt" TIMESTAMP;
+
+-- 创建 HNSW 索引（余弦距离）
+CREATE INDEX idx_project_embedding_cosine
+ON "Project" USING hnsw ("embedding" vector_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- 复合索引（查找未向量化项目）
+CREATE INDEX idx_project_embedding_null
+ON "Project" ("id")
+WHERE "embedding" IS NULL;
+```
+
+### 向量化内容策略
+
+**字段权重分配：**
+- 名称（40%）：`name` + `nameEn`
+- 描述（40%）：`description` + `descriptionEn`
+- 标签（15%）：`tags`（逗号连接）
+- 详细内容（5%）：`content` + `contentEn`（截取前 500 字）
+
+**示例输入文本：**
+```
+AI Video Generator
+一个基于人工智能的视频生成工具，可以自动从文本生成高质量视频...
+人工智能, 视频生成, AIGC
+详细功能介绍...
+```
+
+---
+
+## n8n 工作流设计
+
+### 工作流 1：定时向量化
+
+**触发器**：Cron 表达式（每 5 分钟）
+
+```
+*/5 * * * *
+```
+
+**流程**：
+```
+触发器
+  ↓
+查询未向量化项目（LIMIT 20）
+  ↓
+批量处理（每批 5 个）
+  ↓
+  构造文本内容（合并字段）
+  ↓
+  调用 OpenAI Embeddings API
+  ↓
+  更新数据库 embedding 字段
+  ↓
+  等待 1 秒（控制速率）
+  ↓
+下一批
+```
+
+**PostgreSQL 查询**：
+```sql
+SELECT id, name, "nameEn", description, "descriptionEn",
+       content, "contentEn"
+FROM "Project"
+WHERE "embedding" IS NULL
+  AND "status" = 'ACTIVE'
+LIMIT 20
+```
+
+**错误处理**：
+- API 限流：指数退避重试（1s → 2s → 4s）
+- 最多重试 3 次
+- 失败记录日志
+
+### 工作流 2：AI 搜索
+
+**触发器**：Webhook（`/webhook/ai-search`）
+
+**流程**：
+```
+Webhook 接收查询
+  ↓
+接收参数：{ query, locale, limit, filters }
+  ↓
+调用 OpenAI Embeddings API（生成查询向量）
+  ↓
+PostgreSQL 向量相似度搜索
+  ↓
+应用过滤条件（tags, status）
+  ↓
+格式化结果（添加相似度评分）
+  ↓
+返回 JSON 响应
+```
+
+**PostgreSQL 查询**：
+```sql
+SELECT
+  id, name, "nameEn", slug, description, "descriptionEn",
+  1 - (embedding <=> '{{ query_vector }}'::vector) as similarity
+FROM "Project"
+WHERE "embedding" IS NOT NULL
+  AND "status" = 'ACTIVE'
+ORDER BY embedding <=> '{{ query_vector }}'::vector
+LIMIT {{ limit || 20 }}
+```
+
+**响应格式**：
+```json
+{
+  "results": [
+    {
+      "project": { /* 项目数据 */ },
+      "similarity": 0.89,
+      "matchReason": "项目名称和描述与图像生成高度相关"
+    }
+  ],
+  "total": 42,
+  "searchTime": 156
+}
+```
+
+---
+
+## Next.js API 设计
+
+### 路由配置
+
+**文件**：`src/app/api/search/ai/route.ts`
+
+```typescript
+import { NextResponse } from 'next/server'
+
+const N8N_WEBHOOK_URL = process.env.N8N_AI_SEARCH_WEBHOOK
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json()
+
+    // 转发到 n8n 工作流
+    const n8nResponse = await fetch(N8N_WEBHOOK_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    })
+
+    const results = await n8nResponse.json()
+
+    return NextResponse.json(results)
+
+  } catch (error) {
+    return NextResponse.json(
+      { error: 'Search failed' },
+      { status: 500 }
+    )
+  }
+}
+```
+
+**请求格式**：
+```json
+{
+  "query": "帮我找做图像生成的AI工具",
+  "locale": "zh",
+  "limit": 20,
+  "filters": {
+    "tags": ["AIGC"],
+    "status": "ACTIVE"
+  }
+}
+```
+
+---
+
+## 前端交互设计
+
+### UI 组件修改
+
+**文件**：`src/components/search/SearchBar.tsx`
+
+**功能**：
+- 添加 AI 模式切换按钮（Sparkles 图标）
+- AI 模式时按钮高亮（金色背景）
+- 不同模式的占位符提示
+- 加载状态优化
+
+**关键代码**：
+```tsx
+<button
+  onClick={() => setAiMode(!aiMode)}
+  className={`
+    px-3 py-2 border-2 transition-all
+    ${aiMode
+      ? 'bg-yellow-400 border-yellow-500 text-black'
+      : 'bg-white border-gray-300 text-gray-600'
+    }
+  `}
+  title="AI 语义搜索"
+>
+  <Sparkles className="w-5 h-5" />
+</button>
+```
+
+### AI 搜索结果展示
+
+**文件**：`src/components/search/AISearchResults.tsx`
+
+**功能**：
+- 显示相似度指示条（左侧彩色条）
+- 相似度评分（0-100%）
+- 匹配原因说明（可选）
+- 颜色编码：绿色（>0.8）、黄色（>0.6）、红色（<0.6）
+
+### 搜索模式对比
+
+| 特性 | 传统搜索 | AI 搜索 |
+|------|---------|---------|
+| 占位符 | "搜索项目名称..." | "描述你想要的项目..." |
+| 匹配方式 | 关键词模糊匹配 | 向量语义相似度 |
+| 返回速度 | 极快（<100ms） | 较快（1-3s） |
+| 结果增强 | 无 | 相似度评分 + 匹配原因 |
+| 提示信息 | 无 | "💡 试试：'帮我找能生成视频的 AI 工具'" |
+
+---
+
+## 环境变量配置
+
+### Next.js 应用（`.env.local`）
+
+```bash
+# Neon 数据库（已有）
+DATABASE_URL=postgres://...
+
+# n8n Webhook
+N8N_AI_SEARCH_WEBHOOK=https://your-n8n-instance.com/webhook/ai-search
+N8N_WEBHOOK_API_KEY=your-webhook-key  # 可选，用于安全验证
+```
+
+### n8n 工作流
+
+```bash
+# OpenAI API（用于 Embeddings）
+OPENAI_API_KEY=sk-...
+
+# Neon 数据库（与 Next.js 共享）
+NEON_DATABASE_URL=postgres://...
+```
+
+---
+
+## 错误处理与优化
+
+### 错误处理策略
+
+**n8n 工作流**：
+- API 限流：指数退避重试
+- API Key 无效：发送告警
+- 数据库查询失败：返回友好错误信息
+- 向量未就绪：提示用户稍后重试
+
+**前端**：
+- 10 秒超时限制
+- 超时或错误时自动降级到传统搜索
+- Toast 消息提示用户
+
+### 性能优化
+
+**数据库查询**：
+- 只返回必要字段（不返回 content）
+- 使用 HNSW 索引
+- 设置查询超时（5s）
+
+**缓存策略（可选）**：
+- Redis 缓存常见查询结果（5 分钟 TTL）
+- 内存缓存热门查询
+
+### 监控指标
+
+- 平均搜索响应时间
+- API 调用次数/成本
+- 向量化完成率
+- 错误率
+
+---
+
+## 成本估算
+
+### OpenAI Embeddings API
+
+**定价**：
+- text-embedding-3-small：$0.00002 / 1K tokens
+
+**估算**：
+- 单个项目（500 tokens）：$0.00001
+- 1000 个项目：$0.01
+- 单次搜索（10 tokens）：$0.0000002
+- 1000 次搜索：$0.0002
+
+**月度预算**：$5 可处理 50 万个项目或 2500 万次搜索
+
+### Neon 免费套餐
+
+**限制**：
+- 存储：0.5GB
+- 计算：300 小时/月
+
+**向量存储**：
+- 单个项目（1536 维）：3KB（半精度）
+- 1000 个项目：3MB
+- 10,000 个项目：30MB ✅
+
+**结论**：免费套餐完全够用（可支持 5,000-10,000 个项目）
+
+---
+
+## 测试计划
+
+### 单元测试
+
+```typescript
+// src/__tests__/search.test.ts
+describe('AI Search', () => {
+  it('should handle empty query', async () => {
+    const response = await fetch('/api/search/ai', {
+      method: 'POST',
+      body: JSON.stringify({ query: '' })
+    })
+    expect(response.status).toBe(400)
+  })
+
+  it('should fallback to traditional search on error', async () => {
+    // 测试错误降级逻辑
+  })
+})
+```
+
+### E2E 测试
+
+```typescript
+// tests/e2e/ai-search.spec.ts
+test('AI 搜索功能', async ({ page }) => {
+  await page.goto('/zh/projects')
+  await page.click('[data-testid="ai-mode-toggle"]')
+  await page.fill('input[name="search"]', '视频生成工具')
+  await page.press('input[name="search"]', 'Enter')
+  await expect(page.locator('.ai-search-results')).toBeVisible()
+})
+```
+
+### 集成测试
+
+- 测试 n8n 工作流端到端
+- 验证向量搜索结果准确性
+- 测试错误场景（API 限流、数据库连接失败）
+
+---
+
+## 部署清单
+
+### 数据库准备
+
+- [x] 运行数据库迁移
+- [x] 验证 pgvector 扩展已启用
+- [x] 检查 HNSW 索引创建成功
+
+### n8n 配置
+
+- [ ] 创建向量化工作流
+  - [ ] 配置 Cron 触发器（每 5 分钟）
+  - [ ] 配置 PostgreSQL 节点
+  - [ ] 配置 OpenAI Embeddings 节点
+  - [ ] 添加错误处理和重试逻辑
+
+- [ ] 创建 AI 搜索工作流
+  - [ ] 配置 Webhook 触发器
+  - [ ] 配置 OpenAI Embeddings 节点
+  - [ ] 配置 PostgreSQL 向量查询
+  - [ ] 配置结果格式化
+
+- [ ] 测试工作流
+  - [ ] 手动触发向量化流程
+  - [ ] 测试 Webhook 搜索
+  - [ ] 验证错误处理
+
+### Next.js 部署
+
+- [ ] 添加环境变量（N8N_WEBHOOK_URL）
+- [ ] 创建 API 路由（`/api/search/ai`）
+- [ ] 更新 SearchBar 组件
+- [ ] 创建 AISearchResults 组件
+- [ ] 本地测试完整流程
+- [ ] 部署到 Vercel
+
+### 验证步骤
+
+1. **向量化测试**：
+   ```sql
+   -- 检查已向量化项目数
+   SELECT COUNT(*) FROM "Project" WHERE embedding IS NOT NULL;
+   ```
+
+2. **搜索测试**：
+   - 输入自然语言查询
+   - 验证返回结果相关性
+   - 检查相似度评分
+
+3. **性能测试**：
+   - 测量平均响应时间
+   - 验证并发处理能力
+
+---
+
+## 后续优化方向
+
+1. **混合搜索**：结合关键词搜索和向量搜索，提升准确率
+2. **查询缓存**：Redis 缓存热门查询结果
+3. **A/B 测试**：对比传统搜索和 AI 搜索的用户体验
+4. **多模态搜索**：支持图片、语音输入
+5. **个性化排序**：基于用户历史行为优化结果
+6. **自动标签建议**：AI 分析项目内容推荐标签
+
+---
+
+## 参考资料
+
+- [Neon pgvector 文档](https://neon.com/docs/extensions/pgvector)
+- [OpenAI Embeddings API](https://platform.openai.com/docs/guides/embeddings)
+- [pgvector GitHub](https://github.com/pgvector/pgvector)
+- [HNSW 算法论文](https://arxiv.org/abs/1603.09320)