Vectorize 与 Workers AI

Vectorize 允许你使用机器学习模型（包括 Workers AI 中的模型）生成向量嵌入。

本指南将带你完成：

创建 Vectorize 索引。
将 Cloudflare Worker 连接到你的索引。
使用 Workers AI 生成向量嵌入。
使用 Vectorize 查询这些向量嵌入。

前提条件

继续之前，你需要：

若尚未注册，请注册 Cloudflare 账户 ↗。
安装 npm ↗。
安装 Node.js ↗。建议使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器，避免权限问题并切换 Node.js 版本。Wrangler 需要 Node 版本 16.17.0 或更高。

1. 创建 Worker

你将创建一个新项目，其中包含作为 Vectorize 索引客户端应用的 Worker 脚本。

打开终端，运行以下命令创建名为 embeddings-tutorial 的新项目：

npm create cloudflare@latest -- embeddings-tutorial

yarn create cloudflare embeddings-tutorial

pnpm create cloudflare@latest embeddings-tutorial

进行设置时，请选择以下选项：

对于 What would you like to start with?，选择 Hello World example。
对于 Which template would you like to use?，选择 Worker only。
对于 Which language do you want to use?，选择 TypeScript。
对于 Do you want to use git for version control?，选择 Yes。
对于 Do you want to deploy your application?，选择 No（部署前我们还会做一些修改）。

这将创建新的 embeddings-tutorial 目录，其中包含：

位于 src/index.ts 的 "Hello World" Worker。
wrangler.jsonc 配置文件。embeddings-tutorial Worker 通过 wrangler.jsonc 访问索引。

2. 创建索引

向量数据库与传统 SQL 或 NoSQL 数据库不同，专为存储向量嵌入（数据的表示形式，而非原始数据本身）而设计。

要创建第一个 Vectorize 索引，请进入刚为 Workers 项目创建的目录：

cd embeddings-tutorial

要创建索引，需使用 wrangler vectorize create 命令并提供索引名称。良好的索引名称应：

由小写和/或数字 ASCII 字符组合而成，少于 32 个字符，以字母开头，用连字符（-）代替空格。
能描述用例和环境，例如 "production-doc-search" 或 "dev-recommendation-engine"。
仅用于描述索引，代码中不直接引用。

此外，还需定义要存储向量的 dimensions（维度），以及创建索引时用于判定相似向量的距离 metric（度量）。此配置创建后无法更改，因为向量数据库针对固定向量配置进行优化。

运行以下 wrangler vectorize 命令，确保 dimensions 设为 768：这很重要，因为本教程使用的 Workers AI 模型输出 768 维向量。

npx wrangler vectorize create embeddings-index --dimensions=768 --metric=cosine

✅ Successfully created index 'embeddings-index'

[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "embeddings-index"

上述命令将创建新的向量数据库，并输出下一步所需的绑定（binding）配置。

3. 将 Worker 绑定到索引

Worker 必须创建绑定才能连接 Vectorize 索引。绑定（binding）使 Worker 能够访问 Cloudflare Workers 上的 Vectorize 或 R2 等资源。通过更新 Wrangler 文件创建绑定。

要将索引绑定到 Worker，请在 Wrangler 文件末尾添加：

{
	"vectorize": [
		{
			"binding": "VECTORIZE", // available in your Worker on env.VECTORIZE
			"index_name": "embeddings-index"
		}
	]
}

[[vectorize]]
binding = "VECTORIZE"
index_name = "embeddings-index"

具体说明：

为 <BINDING_NAME> 设置的值（字符串）将在 Worker 中引用此数据库。本教程中将绑定命名为 VECTORIZE。
绑定必须是有效的 JavaScript 变量名 ↗。例如 binding = "MY_INDEX" 或 binding = "PROD_SEARCH_INDEX" 均为有效名称。
绑定在 Worker 中可通过 env.<BINDING_NAME> 访问，Vectorize 客户端 API 在此绑定上暴露，供 Workers 应用使用。

4. 设置 Workers AI

在部署嵌入示例之前，请确保 Worker 使用模型目录，包括内置的文本嵌入模型。

在 embeddings-tutorial 目录中，在编辑器中打开 Wrangler 文件，添加新的 [[ai]] 绑定，使 Workers AI 的模型在 Worker 中可用：

{
	"vectorize": [
		{
			"binding": "VECTORIZE",
			"index_name": "embeddings-index"
		}
	],
	"ai": {
		"binding": "AI" // available in your Worker on env.AI
	}
}

[[vectorize]]
binding = "VECTORIZE"
index_name = "embeddings-index"

[ai]
binding = "AI"

Workers AI 就绪后，即可在 Worker 中编写代码。

5. 在 Worker 中编写代码

要在 Worker 中编写代码，请进入 embeddings-tutorial Worker 并打开 src/index.ts 文件。index.ts 是配置 Worker 与 Vectorize 索引交互的地方。

清空 index.ts 的内容。将以下代码片段粘贴到 index.ts 中。在 env 参数上，将 <BINDING_NAME> 替换为 VECTORIZE：

export interface Env {
	VECTORIZE: Vectorize;
	AI: Ai;
}
interface EmbeddingResponse {
	shape: number[];
	data: number[][];
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let path = new URL(request.url).pathname;
		if (path.startsWith("/favicon")) {
			return new Response("", { status: 404 });
		}

		// You only need to generate vector embeddings once (or as
		// data changes), not on every request
		if (path === "/insert") {
			// In a real-world application, you could read content from R2 or
			// a SQL database (like D1) and pass it to Workers AI
			const stories = [
				"This is a story about an orange cloud",
				"This is a story about a llama",
				"This is a story about a hugging emoji",
			];
			const modelResp: EmbeddingResponse = await env.AI.run(
				"@cf/baai/bge-base-en-v1.5",
				{
					text: stories,
				},
			);

			// Convert the vector embeddings into a format Vectorize can accept.
			// Each vector needs an ID, a value (the vector) and optional metadata.
			// In a real application, your ID would be bound to the ID of the source
			// document.
			let vectors: VectorizeVector[] = [];
			let id = 1;
			modelResp.data.forEach((vector) => {
				vectors.push({ id: `${id}`, values: vector });
				id++;
			});

			let inserted = await env.VECTORIZE.upsert(vectors);
			return Response.json(inserted);
		}

		// Your query: expect this to match vector ID. 1 in this example
		let userQuery = "orange cloud";
		const queryVector: EmbeddingResponse = await env.AI.run(
			"@cf/baai/bge-base-en-v1.5",
			{
				text: [userQuery],
			},
		);

		let matches = await env.VECTORIZE.query(queryVector.data[0], {
			topK: 1,
		});
		return Response.json({
			// Expect a vector ID. 1 to be your top match with a score of
			// ~0.89693683
			// This tutorial uses a cosine distance metric, where the closer to one,
			// the more similar.
			matches: matches,
		});
	},
} satisfies ExportedHandler<Env>;

6. 部署 Worker

在全球部署 Worker 之前，运行以下命令使用 Cloudflare 账户登录：

npx wrangler login

系统将引导你打开网页并登录 Cloudflare 仪表板。登录后，系统会询问 Wrangler 是否可以对 Cloudflare 账户进行更改。向下滚动并选择 Allow（允许） 继续。

接下来，部署 Worker 使项目可在互联网上访问。运行以下命令部署 Worker：

npx wrangler deploy

在 https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev 预览 Worker。

7. 查询索引

现在可以访问新创建项目的 URL，插入向量并查询它们。

使用已部署 Worker 的 URL（例如 https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev/），在浏览器中：

先访问 /insert 插入向量。
访问索引路由 / 查询索引。

应返回以下 JSON：

{
	"matches": {
		"count": 1,
		"matches": [
			{
				"id": "1",
				"score": 0.89693683
			}
		]
	}
}

可通过以下方式扩展此示例：

添加更多输入并生成更大的向量集。
接受 URL 中传递的自定义查询参数，例如通过 URL.searchParams。
使用不同的距离度量创建新索引，观察分数如何随输入变化。

完成本教程后，你已成功创建 Vectorize 索引、使用 Workers AI 生成向量嵌入，并将项目部署到全球。

后续步骤

使用 Workers AI 和 Vectorize 构建生成式 AI 聊天机器人。
了解向量数据库的工作原理。
阅读示例，了解如何从 Cloudflare Workers 使用 Vectorize API。