Vectorize MCP Worker

矢量化MCP工人

Cloudflare Workers上的生产级RAG。约5美元/月。没有服务器。没有松果法案。

混合搜索、知识反射、多模式摄取、元数据过滤、多租户、速率限制和本地MCP服务器——所有这些都在一个可部署的Worker中。


______________________________________________________________________

为什么存在

Andrej Karpathy最近提出了一个令人信服的论点：LLMs正在成为新的维基百科。问模特，得到答案。对于一般知识问题，他是对的——如果你问“什么是梯度下降”，你不需要检索管道。

但这种框架有一个盲点：

您的数据不在任何LLM的训练集中。永远不会。

你的内部文档、客户合同、支持票、财务报告、产品变更日志——这些都不存在于任何模型中。你需要答案的那一刻 *你的* 具体的知识库，需要检索。当你需要被引用、最新且没有幻觉的结果时，你需要RAG。

此项目适用于该用例。它并不是试图在常识方面击败法学硕士。这使它们在 *你的* 数据。

第二个原因是：大多数RAG教程都会给你一个50行的Python脚本，它调用OpenAI和Pinecone，并称之为一天。对于周末的演示来说，这很好。当您需要多租户、元数据过滤、亚秒级缓存响应、适当的MCP服务器以及您在生产中实际信任的东西时，它就会崩溃。这就是当你从一开始就正确构建东西时会发生的事情。

______________________________________________________________________

主要特点

混合搜索 --向量相似度+BM25关键字搜索，与互序融合。纯向量搜索会错过精确匹配。纯关键字搜索会遗漏同义词。你两者都需要。

交叉编码器重新排序 --在初始检索后，交叉编码器会根据您的查询重新排序顶部结果。在我的基准测试中：提高了9.3个百分点MRR@5.

知识反思 *新* --每次摄取后，系统都会找到语义相关的文档，并要求Llama综合哪些是新的，它如何与现有知识联系起来，以及还有什么差距。这些反射在搜索结果中被存储、嵌入和增强。随着您添加更多文档，知识库变得更加智能，而不仅仅是更大。

智能查询路由（V4） --并非每个查询都需要向量搜索。实体查找转到SQL（11ms），精确关键字查询转到BM25（18ms），语义问题转到整个管道。在测试中，与通过向量运行所有内容相比，这将平均嵌入成本降低了71%。

元数据筛选 --筛选条件 source_type, category, doc_type, tags, date_created, tenant_id, mime_type, file_name --使用 $eq, $ne, $in, $gt/$gte/$lt/$lte。过滤器在Vectorize层运行，而不是在内存中运行。

多模态 --通过上传或URL摄取图像。Llama 4 Scout 17B处理视觉+OCR。文本查询可以显示图像结果。一切都存在于一个统一的索引中。

本地MCP服务器 --可流式HTTP /mcp，每个会话由Cloudflare持久对象支持。六种工具： search, ingest, ingest_image_url, find_similar_by_url, delete, stats两行JSON用于连接Claude Desktop。就这样

多租户 --一个部署，多个孤立的租户。通过JSON机密将API密钥映射到租户ID。每个操作都会自动确定范围。租户无法逃脱其命名空间。您不需要为每个客户单独部署。

两层缓存 -Cloudflare Cache API（全局，共享，60s SWR）+内存映射缓存。重复查询的成本为零。

速率限制 --每个租户或IP的滑动窗口限制器。可配置。返回正确 Retry-After 标题。

查询分析 --记录的每个查询：每个阶段的延迟、缓存命中/未命中、使用的过滤器。表面通过 /stats 以及内置的仪表板。没有单独的日志记录服务。

三种嵌入模型 — qwen3-0.6b （1024d，最佳检索质量2026，默认）， bge-m3 （1024d，多语言）， bge-small （384d，遗产）。一个要切换的环境变量： EMBEDDING_MODEL.

______________________________________________________________________

知识反射层

标准RAG检索文档。它不会学习。每一个查询都是冷冰冰的——没有对之前发现的内容的记忆，没有跨文档的综合，也没有对知识库的理解。

反射层改变了这一点。每次摄取文档时：

1. 系统会在索引中找到语义上最相关的文档
2. Gemma 4月(@cf/google/gemma-4-26b-a4b-it)综合三句话的见解：新文档添加了什么，它如何与现有知识联系起来，以及还有什么差距
3. 该反射被嵌入并存储在 doc_type=reflection，并在搜索结果中获得1.5倍的排名提升
4. 每3个新文档后，反思都会合并为 doc_type=summary --知识库所学内容的压缩视图

你的知识库在原始文档之上构建了第二层综合知识。相关概念被明确地联系起来。矛盾浮出水面。搜索结果包括两个原始块 *和* 提炼的见解。

您可以过滤以只看到反射(doc_type: { "$eq": "reflection" })，或将其排除在外("$ne": "reflection")，或者让它们自然地与原始结果一起出现——这是默认设置。

______________________________________________________________________

真实世界用例

内部知识库 --摄取您的Notion导出、Confluence页面、内部文档。为您的团队提供一个理解上下文的搜索界面，而不仅仅是关键字。通过MCP连接Claude Desktop，每个团队成员都可以在您的整个知识库中进行人工智能辅助搜索，而无需您构建任何自定义内容。

SaaS，支持按客户搜索文档 --启用多租户。每个客户在同一部署中都有自己的隔离命名空间。一个Worker，一个Vectorize索引，真正的数据隔离。没有为每位客户提供单独的搜索服务。

法律/合规检索 --摄取合同、文件、政策文件。筛选依据 date_created, category, source_type反射层揭示了文档之间随时间变化的联系，有助于发现不断演变的政策中的矛盾。

了解代码库的开发工具 --记下你的文档、变更日志、运行手册、事故事后分析。把它挂到克劳德桌面上。询问有关您自己的架构决策和事件历史的问题。

收据和发票处理 --上传收据图像，Llama 4 Scout提取文本，包括语义描述和原始OCR索引。搜索“3月份晚餐费用超过100美元”，它就奏效了。

______________________________________________________________________

现场演示

部署后，您的仪表板位于：

https://your-worker.workers.dev/dashboard

OpenAPI规范可在 /openapi.json -将其直接导入Postman、Insomnia、Bruno或任何接受OpenAPI 3.0的API客户端。

这是一个完整的游乐场：使用过滤器和意图分类调试进行搜索，摄取文档（拖放文件上传、高级元数据），上传图像，查找视觉上相似的图像，删除文档，管理许可证，监控缓存命中率，检查哪个嵌入模型处于活动状态，浏览查询分析。内置的“指南”选项卡通过可复制的命令和实时状态检查器遍历每个设置步骤。不是玩具。

______________________________________________________________________

快速开始

您需要：一个Cloudflare帐户（免费层有效），Node.js v18+，Wrangler CLI。

npm install -g wrangler
wrangler login

1.克隆并安装

git clone https://github.com/dannwaneri/vectorize-mcp-worker.git
cd vectorize-mcp-worker
npm install

2.创建矢量化索引

# Default (recommended): qwen3-0.6b, 1024 dimensions
wrangler vectorize create mcp-knowledge-base --dimensions=1024 --metric=cosine

# Legacy (existing 384d deployments): bge-small
# wrangler vectorize create mcp-knowledge-base --dimensions=384 --metric=cosine
# Then set EMBEDDING_MODEL=bge-small in wrangler.toml [vars]

3.创建D1数据库

wrangler d1 create mcp-knowledge-db

复制 database_id 从输出。

4.配置

cp wrangler.toml.example wrangler.toml

粘贴您的 database_id 进入 wrangler.toml。这是唯一需要编辑的。

[[d1_databases]]
binding = "DB"
database_name = "mcp-knowledge-db"
database_id = "paste-your-id-here"

5.应用模式并部署

wrangler d1 execute mcp-knowledge-db --remote --file=./schema.sql
wrangler d1 execute mcp-knowledge-db --remote --file=./migrations/001_add_tenant_id.sql
wrangler d1 execute mcp-knowledge-db --remote --file=./migrations/002_add_reflection_fields.sql
wrangler deploy

6.设置API密钥

wrangler secret put API_KEY

完成。访问 https://your-worker.workers.dev/test 以确认所有内容都已连接。

更喜欢点击一下？ 顶部的部署按钮会自动脚手架一切。你仍然需要设置 API_KEY 作为事后的秘密。

______________________________________________________________________

克劳德桌面和MCP集成

MCP服务器运行在 /mcp 使用流式HTTP传输（2026标准）。每个会话都会获得一个用于隔离状态的专用持久对象实例。六种工具覆盖了整个生命周期。

克劳德桌面版

将以下内容添加到您的配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vectorize": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker.workers.dev/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

重新启动克劳德桌面。这六个工具出现在工具选择器中。然后：

*“在我的知识库中搜索有关我们第一季度定价决策的任何信息”* *“摄取此文档--将其标记为类别：财务，源类型：pdf”* *“我们对基础设施成本有什么综合见解？”* *“查找与此URL类似的图像，并向我显示前5个”*

Cursor、Windsurf或任何本机可流式传输HTTP客户端

{
  "mcpServers": {
    "vectorize": {
      "url": "https://your-worker.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

可用工具

所有工具都会从API密钥自动确定租户的范围。您不能意外读取其他租户的数据。

______________________________________________________________________

技术栈

一切都在Cloudflare上运行。没有外部服务。无第三方计费。没有数据离开您的帐户。

切换嵌入模型是一个环境变量(EMBEDDING_MODEL).切换反射质量与成本是一个环境变量(REFLECTION_MODEL=llama-3.2-3b 为了降低成本）。从以下位置切换 bge-small （384天）至 qwen3-0.6b （1024d）需要一个新的Vectorize索引并重新摄取——无需更改代码。

______________________________________________________________________

成本

直接的数字，没有模糊的“比松果便宜”的手势。

V4智能路由每天1000次查询：

• 约0.11美元/月——大多数查询都会到达SQL或BM25路由，不需要嵌入
• ~0.39美元/月——如果每个查询都经过完整的向量管道（V3模式）
• ~$0/月缓存——一旦查询进入CF缓存，再次提供服务就不需要任何费用

每天10000次查询： 根据查询组合和缓存命中率，每月大约1-5美元。

Cloudflare Workers免费层在您支付任何计算费用之前每天处理100000个请求。Vectorize、D1和Workers AI也都有自己的免费等级。在大多数球队实际运行的数量上，总账单以最好的方式是无聊的。

______________________________________________________________________

比较

如果你的数据是公共知识，新鲜度并不重要，那么法学硕士通常是正确的选择。如果你的数据是私有的、专有的或时间敏感的，你需要检索。这是我找到的通往生产级检索的最快路径，也是这份列表中唯一一条知识库随着时间的推移变得更智能的路径。

______________________________________________________________________

路线图

• \[x\] 批量摄入 — POST /ingest/batch，最多100个文档，并发控制，每个文档结果
• \[x\] 图像URL分析 — POST /analyze-image，获取任何公共图像URL并返回AI描述（Llama 4 Scout），而无需摄入——这对于在索引之前丰富外部内容非常有用
• \[x\] 反射回填 — POST /reflect/batch，对N个未反映的原始文档进行采样，并根据需要生成知识反映——定期运行以建立综合，而不会阻止摄取
• \[ \] 增量重新索引 --更新文档元数据而不完全重新嵌入
• \[ \] Webhook支持 --从Notion、GitHub、Slack事件触发摄取
• \[x\] OpenAPI规范 — GET /openapi.json，OpenAPI 3.0.3，可导入邮差/失眠/布鲁诺
• \[x\] 测试套件 --73个单元测试，涵盖分块、身份验证、速率限制和批量摄入

PR欢迎参与其中任何一项活动。如果您在生产环境中运行此程序并遇到特定问题，请打开一个问题，我会优先处理它。

______________________________________________________________________

贡献与反馈

如果这为你节省了时间或金钱，GitHub上的明星会帮助其他人找到它。

如果有什么东西坏了或令人困惑， 打开一个问题我读过每一本。

代码库故意简单明了——框架之上没有框架。目前最有价值的贡献是真实世界的使用报告、批处理摄取端点以及中间件和反射层的测试覆盖率。

______________________________________________________________________

专业服务

需要部署、定制或集成到现有产品中吗？

• 设置和入职： 2500美元一次性-全面部署，最多1万个文档索引，2周支持
• 雇用我上Upwork

______________________________________________________________________

许可证

麻省理工学院——见 许可证.

______________________________________________________________________

丹尼尔·恩瓦内里 --在Cloudflare Workers上构建有用的东西

推特 · 自由职业平台 · DEV.to ·