[Feature] 向量语义搜索 — 让 AI 搜索真正理解语义

[AmintaCCCP]

🎯 要解决的问题

当前的 AI 搜索本质上仍是关键词搜索：LLM 提取关键词/同义词 → 本地子串匹配。它无法理解语义关系：

• 搜索 管理 Docker 的工具 → ❌ 无法匹配描述为 "container orchestration platform" 的仓库
• 搜索 好看的终端 → ❌ 无法匹配 "beautiful terminal emulator with GPU acceleration"
• 搜索 轻量级数据库 → ❌ 无法匹配 "embedded key-value store written in Rust"

💡 方案概述

引入向量语义搜索作为可选增强功能，基于 Cloudflare Vectorize：

用户输入 → Embedding API 生成查询向量 → Vectorize ANN 搜索 → 返回语义最相关的仓库

核心设计

1. Embedding 模型自由配置 — 支持 OpenAI / Gemini / Cohere / Ollama(本地) / 任意 OpenAI 兼容端点（包括中转站）
2. Cloudflare Worker 做纯代理 — Worker 不持有任何 AI Key，只做 Vectorize 的存/查/删
3. 纯可选，零侵入 — 不启用时所有行为不变；启用后向量查询失败自动回退到现有关键词搜索

架构

前端 App
├── 调用用户配置的 Embedding API（支持任意渠道）
└── 将向量发送到 Worker → 存入 Vectorize

搜索时:
用户输入 → 前端调 Embedding API → 查询向量发到 Worker → Vectorize ANN → 返回结果

📋 具体内容

Embedding 配置（独立于 AI 分析配置）

渠道	示例配置
OpenAI 官方	text-embedding-3-small, 1536维, $0.02/M tokens
OpenAI 中转站	任意兼容 /v1/embeddings 的端点
Gemini	text-embedding-004, 768维, 免费
Ollama 本地	nomic-embed-text, 768维, 完全免费
LM Studio / vLLM	本地部署的任意模型

Cloudflare 免费额度够用吗？

资源	免费额度	2000 repos 消耗
Workers 请求	100,000/天	每次搜索 1 请求 ✅
Vectorize 存储	5M 维度/月	2000×1536 = 3.07M ✅
Vectorize 查询	30M 维度/月	100次/天×30天 = 4.6M ✅

搜索流程

向量搜索启用？
├─ 否 → 现有 AI 关键词搜索（不变）
└─ 是 → 前端生成查询向量 → Worker ANN 搜索 → 按相似度排序
           ↓ (失败时)
         自动回退到关键词搜索

🤔 讨论点

1. Embedding 模型推荐 — 大家倾向用哪个？Ollama 本地优先？还是直接用 OpenAI？
2. 向量维度选择 — 768 vs 1024 vs 1536，精度和存储的取舍
3. 文本拼接策略 — 索引时用哪些字段？description + ai_summary + topics + README？
4. 是否需要 README 全文 — 当前 README 不持久化，向量化需要存 README 内容吗？
5. 部署门槛 — Cloudflare Worker 的部署流程对非技术用户是否友好？有没有更简单的替代方案？
6. 其他想法 — 欢迎提出更好的方案或补充

---

📎 详细技术方案：
vector-search-design.md

[AmintaCCCP]

完整技术方案

一、背景与目标

现状： 当前 AI 搜索流程：LLM 提取关键词/同义词 → 本地子串匹配。本质上仍是关键词搜索。

目标： 引入向量语义搜索作为可选增强功能：

• 用户部署一个极简的 Cloudflare Worker（纯 Vectorize 代理）
• 用户在 App 设置中配置 Embedding 模型（支持任意渠道，包括本地 Ollama）
• 启用后，AI 搜索优先走向量检索，失败时自动回退

设计原则：

1. 纯可选：不启用时所有行为不变
2. Embedding 配置自由：支持 OpenAI / Gemini / Cohere / DeepSeek / Ollama / 任意 OpenAI 兼容端点 / 本地模型
3. Worker 极简：Worker 不持有任何 AI Key，只做 Vectorize 的存/查/删代理
4. 优雅降级：向量查询失败 → 自动回退到现有关键词搜索

---

二、架构总览

┌──────────────────────────────────────────────────────────────────────┐
│                          前端 (React SPA)                             │
│                                                                      │
│  ┌──────────────┐  ┌─────────────────────┐  ┌────────────────────┐  │
│  │ AI 分析配置    │  │ Embedding 配置 (新增) │  │ Vectorize 配置 (新增)│  │
│  │ (已有, 不变)   │  │ baseUrl+apiKey+model │  │ workerUrl+authToken│  │
│  └──────┬───────┘  └──────────┬──────────┘  └─────────┬──────────┘  │
│         │                     │                       │             │
│         │              ┌──────▼──────┐                │             │
│         │              │ 调用 Embedding│                │             │
│         │              │ API 生成向量  │                │             │
│         │              └──────┬──────┘                │             │
│         │                     │ 向量数据              │             │
│         │              ┌──────▼───────────────────────▼──────┐      │
│         │              │    vectorSearchService.ts (新增)      │      │
│         │              │  embedText → upsert/query/delete     │      │
│         │              └──────────────────┬───────────────────┘      │
│         │                                 │ HTTPS                    │
└─────────┼─────────────────────────────────┼──────────────────────────┘
          │                                 │
          ▼                                 ▼
   ┌──────────────┐              ┌─────────────────────────┐
   │ AI 分析 API   │              │  Cloudflare Worker       │
   │ (用户自有)     │              │  (用户自部署, ~120行)     │
   └──────────────┘              │  纯 Vectorize 代理       │
                                 │  不持有任何 AI Key       │
   ┌──────────────┐              └────────────┬────────────┘
   │ Embedding API │                           │
   │ (用户自有)     │              ┌────────────▼────────────┐
   │ 支持:         │              │    Cloudflare Vectorize  │
   │ - OpenAI      │              │    HNSW ANN 向量数据库    │
   │ - Gemini      │              └─────────────────────────┘
   │ - Cohere      │
   │ - Ollama      │
   │ - 任意兼容端点  │
   │ - 本地模型     │
   └──────────────┘

关键设计决策：Worker 不负责 Embedding，只做 Vectorize 代理。

职责	承担者	理由
Embedding 生成	前端	支持任意渠道（Ollama、中转站、本地模型）
向量存储/查询	Worker → Vectorize	需要 HNSW 索引
Embedding 配置管理	前端	复用现有 AI 配置的 UI 和存储模式

---

三、Embedding 配置设计

Embedding 配置与现有 AI 分析配置结构类似但完全独立：

export type EmbeddingApiType =
  | 'openai'            // OpenAI /v1/embeddings
  | 'openai-compatible' // 任意兼容端点
  | 'gemini'            // Google Gemini
  | 'cohere'            // Cohere
  | 'ollama';           // Ollama 本地

export interface EmbeddingConfig {
  id: string;
  name: string;
  apiType: EmbeddingApiType;
  baseUrl: string;
  apiKey: string;          // Ollama 可为空
  model: string;
  dimensions: number;      // 必须与 Vectorize 索引一致
  isActive: boolean;
}

各渠道配置示例：

渠道	apiType	baseUrl	model	dimensions	apiKey
OpenAI 官方	openai	https://api.openai.com	text-embedding-3-small	1536	sk-xxx
OpenAI 中转站	openai	https://api.example.com	text-embedding-3-small	1536	sk-xxx
Gemini	gemini	https://generativelanguage.googleapis.com	text-embedding-004	768	AIza-xxx
Cohere	cohere	https://api.cohere.com	embed-multilingual-v3.0	1024	xxx
Ollama 本地	ollama	http://localhost:11434	nomic-embed-text	768	(留空)
LM Studio	openai-compatible	http://localhost:1234	text-embedding-nomic	768	lm-studio
vLLM 本地	openai-compatible	http://localhost:8000	bge-m3	1024	(留空)

核心：用户填什么就用什么，不限制渠道。

---

四、Worker 设计（极简化，约120行）

Worker 完全不知道 Embedding 模型的存在，只做三件事：

POST /upsert  → 接收预计算的向量 → 写入 Vectorize
POST /query   → 接收查询向量 → Vectorize ANN 搜索 → 返回 IDs + scores
POST /delete  → 删除指定向量
GET  /status  → 返回索引信息

Worker 完整代码仅约 120 行，没有任何 AI 相关逻辑，没有环境变量持有 API Key。只是一个带认证的 Vectorize 代理。

Vectorize 索引创建：

npx wrangler vectorize create github-stars --dimensions=1536 --metric=cosine

---

五、搜索流程

用户输入 "能帮我管理 docker 容器的工具"
  │
  ▼
向量搜索已启用？
  ├─ 否 → 现有 AI 关键词搜索（不变）
  └─ 是 ↓
      前端调用 Embedding API → 生成查询向量
      POST /query → Worker → Vectorize ANN 搜索
      返回 [{id, score, metadata}]
      前端从 IndexedDB 取完整 repo 数据
      按相似度排序 → applyFilters() → 展示
      │
      ▼ (如果任何步骤失败)
      自动回退到现有 AI 关键词搜索

---

六、同步流程

触发时机	行为	阻塞?
AI 分析完成后	为新 repo 生成 embedding 并 upsert	否，异步
用户手动 "重建向量索引"	全量重新索引	否，显示进度条
用户 unstar	从 Vectorize 删除对应向量	否

文本拼接策略：

full_name + description + custom_description + ai_summary
+ topics + ai_tags + custom_tags + language

---

七、成本分析

Cloudflare 免费额度：

资源	免费额度	2000 repos 消耗
Workers 请求	100,000/天	每次搜索 1 请求 ✅
Vectorize 存储	5M 维度/月	2000×1536 = 3.07M ✅
Vectorize 查询	30M 维度/月	100次/天×30天 = 4.6M ✅

Embedding API 成本：

渠道	2000 repos 全量	月度总计
OpenAI text-embedding-3-small	~$0.02	~$0.02
Gemini text-embedding-004	免费	$0
Ollama 本地 nomic-embed-text	免费	$0
Cohere embed-multilingual-v3	~$0.10	~$0.10

---

八、实现计划

• Phase 1: 核心服务 — EmbeddingClient + VectorSearchService
• Phase 2: Worker 模板 — 约120行代码 + 部署指南
• Phase 3: 前端设置 UI — Embedding 配置 + Worker 配置 + 状态 + 进度条
• Phase 4: 后端支持 — 新增数据库表 + API 路由 + autoSync
• Phase 5: 搜索集成 — handleAISearch 改造 + 回退逻辑
• Phase 6: 同步集成 — 增量索引 + 全量重建 + 删除同步

---

九、风险与限制

风险	缓解措施
Ollama CORS 问题	配置 OLLAMA_ORIGIN=* 或通过后端代理
维度不匹配	测试连接时校验，不匹配阻止启用
切换模型需重建索引	UI 明确提示，自动触发重建
大量 repo 首次索引耗时	分批处理 + 进度条 + 可中止
前端持有 API Key	与现有 AI 分析同一安全等级

---

附录：Embedding 模型参考

模型	维度	多语言	价格	推荐场景
OpenAI text-embedding-3-small	1536	✅	$0.02/M	通用，性价比高
OpenAI text-embedding-3-large	3072	✅	$0.13/M	精度要求高
Gemini text-embedding-004	768	✅	免费	成本敏感
Cohere embed-multilingual-v3.0	1024	✅	$0.1/M	多语言最佳
Ollama nomic-embed-text	768	✅	免费	本地，隐私优先
Ollama bge-m3	1024	✅	免费	本地，多语言

欢迎提出意见和建议！🙏