feat: 向量语义搜索 — Cloudflare Vectorize 集成

cloudflare-worker/README.md

@@ -0,0 +1,143 @@
+# GitHub Stars Vectorize Worker
+
+极简 Cloudflare Worker，作为 Cloudflare Vectorize 的代理。前端负责 Embedding 生成，Worker 只负责向量的存/查/删。
+
+## 前置条件
+
+- [Cloudflare 账号](https://dash.cloudflare.com/)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) (`npm install -g wrangler`)
+- 已登录 Wrangler (`wrangler login`)
+
+## 首次部署
+
+### 1. 创建 Vectorize 索引
+
+索引维度必须与你选择的 Embedding 模型一致：
+
+```bash
+# OpenAI text-embedding-3-small (1536维)
+npx wrangler vectorize create github-stars --dimensions=1536 --metric=cosine
+
+# Ollama nomic-embed-text (768维)
+npx wrangler vectorize create github-stars --dimensions=768 --metric=cosine
+
+# Cohere embed-multilingual-v3.0 (1024维)
+npx wrangler vectorize create github-stars --dimensions=1024 --metric=cosine
+
+# Gemini text-embedding-004 (768维)
+npx wrangler vectorize create github-stars --dimensions=768 --metric=cosine
+
+# 硅基流动 BAAI/bge-large-zh-v1.5 (1024维)
+npx wrangler vectorize create github-stars --dimensions=1024 --metric=cosine
+```
+
+### 2. 安装依赖
+
+```bash
+npm install
+```
+
+### 3. 设置认证令牌
+
+```bash
+wrangler secret put AUTH_TOKEN
+# 输入一个安全的随机字符串，例如：openssl rand -hex 32
+```
+
+### 4. 部署
+
+```bash
+npm run deploy
+```
+
+部署成功后，Wrangler 会输出 Worker 的 URL，格式类似：
+```text
+https://github-stars-vectorize.<your-subdomain>.workers.dev
+```
+
+### 5. 在 App 中配置
+
+在 GitHub Stars Manager 的 **设置 → 向量搜索** 中：
+- **Worker 地址**: 填入上一步的 URL
+- **认证 Token**: 填入你设置的 AUTH_TOKEN 值
+
+### 6. 测试连接
+
+在设置页点击 **测试 Worker 连接**，看到 "连接成功" 即可。
+
+---
+
+## 更新部署（代码变更后）
+
+当你更新了 Worker 代码（例如从 GitHub 拉取了新版本），需要重新部署：
+
+```bash
+cd cloudflare-worker
+
+# 如果依赖有变更（package.json 更新了）
+npm install
+
+# 重新部署
+npm run deploy
+```
+
+> **注意**：更新部署**不需要**重新创建 Vectorize 索引，已有向量数据不受影响。
+
+---
+
+## 更换 Embedding 模型
+
+> ⚠️ **更换模型后必须重建索引！** 不同模型生成的向量维度不同，混用会导致查询失败。
+
+步骤：
+1. 在 App 设置中更换 Embedding 模型
+2. 如果新模型的维度与旧模型不同，需要**删除旧索引并创建新索引**：
+   ```bash
+   # 删除旧索引
+   npx wrangler vectorize delete github-stars
+
+   # 创建新索引（维度与新模型一致）
+   npx wrangler vectorize create github-stars --dimensions=1024 --metric=cosine
+   ```
+3. 在 App 中点击 **重建向量索引**
+
+---
+
+## 文件说明
+
+| 文件 | 说明 |
+|------|------|
+| `src/index.ts` | Worker 源码（TypeScript，CLI 部署使用） |
+| `worker.js` | Worker 代码（纯 JS，备用） |
+| `wrangler.toml` | Wrangler 部署配置 |
+| `package.json` | 依赖声明 |
+
+## API 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/upsert` | 批量写入向量 |
+| POST | `/query` | 向量相似度查询 |
+| POST | `/delete` | 删除指定向量 |
+| POST | `/cleanup` | 清理不在 keepIds 列表中的向量 |
+| GET | `/status` | 获取索引状态 |
+
+所有请求需要 `Authorization: Bearer <AUTH_TOKEN>` 头。
+
+## 本地开发
+
+```bash
+npm run dev
+```
+
+## 常见 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** | ✅ | 免费 |
+| 硅基流动 BAAI/bge-large-zh-v1.5 | **1024** | ✅ | ¥0.5/M |