跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

自定义元数据

最后更新 查看 MarkdownAgent 设置

AI Gateway 中的自定义元数据允许你使用用户 ID 或其他标识符标记请求,从而更好地跟踪和分析请求。元数据值可以是字符串、数字或布尔值,并会显示在日志中,便于搜索和过滤数据。

主要功能

  • 自定义标记:向请求添加用户 ID、团队名称、测试指示符和其他相关信息。
  • 增强日志:元数据会出现在日志中,便于详细检查和排查问题。
  • 搜索与过滤:使用元数据高效搜索和过滤已记录的请求。

支持的元数据类型

  • 字符串
  • 数字
  • 布尔值

保留的元数据

以 cf. 开头的元数据键保留给 Cloudflare 添加的元数据。不要发送自己定义的 cf.* 元数据键。AI Gateway 在保存请求元数据之前,会移除客户提供的 cf.* 键。

如果请求通过受 Cloudflare Access 保护的自定义域名到达 AI Gateway,AI Gateway 会将通过身份验证的 Access 用户 ID 作为 cf.user_id 加入请求元数据。该值来自已验证的 Access JWT sub 声明,而不是用户的电子邮件地址。

只要存在有效的 Access 用户 ID,AI Gateway 就保证保存 cf.user_id。如果请求已有五个自定义元数据条目,AI Gateway 可能移除最后一个自定义条目,以便保存 cf.user_id。服务令牌请求和没有用户主体的请求不会获得 cf.user_id 元数据。

实现方式

使用 cURL

要使用 cURL 在请求中包含自定义元数据:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header 'cf-aig-metadata: {"team": "AI", "user": 12345, "test":true}' \
  --data '{"model": "openai/gpt-4.1", "messages": [{"role": "user", "content": "What should I eat for lunch?"}]}'

使用 SDK

要使用 OpenAI SDK 在请求中包含自定义元数据:

import OpenAI from "openai";

export default {
	async fetch(request, env, ctx) {
		const openai = new OpenAI({
			apiKey: env.CLOUDFLARE_API_TOKEN,
			baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/v1`,
		});

		try {
			const chatCompletion = await openai.chat.completions.create(
				{
					model: "openai/gpt-4.1",
					messages: [{ role: "user", content: "What should I eat for lunch?" }],
					max_tokens: 50,
				},
				{
					headers: {
						"cf-aig-metadata": JSON.stringify({
							user: "JaneDoe",
							team: 12345,
							test: true,
						}),
					},
				},
			);

			const response = chatCompletion.choices[0].message;
			return new Response(JSON.stringify(response));
		} catch (e) {
			console.log(e);
			return new Response(e);
		}
	},
};
import OpenAI from "openai";

export default {
	async fetch(request, env, ctx) {
		const openai = new OpenAI({
			apiKey: env.CLOUDFLARE_API_TOKEN,
			baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/v1`,
		});

		try {
			const chatCompletion = await openai.chat.completions.create(
				{
					model: "openai/gpt-4.1",
					messages: [{ role: "user", content: "What should I eat for lunch?" }],
					max_tokens: 50,
				},
				{
					headers: {
						"cf-aig-metadata": JSON.stringify({
							user: "JaneDoe",
							team: 12345,
							test: true,
						}),
					},
				},
			);

			const response = chatCompletion.choices[0].message;
			return new Response(JSON.stringify(response));
		} catch (e) {
			console.log(e);
			return new Response(e);
		}
	},
};

使用 Binding

要使用绑定(Bindings)在请求中包含自定义元数据:

export default {
	async fetch(request, env, ctx) {
		const aiResp = await env.AI.run(
			"@cf/mistral/mistral-7b-instruct-v0.1",
			{ prompt: "What should I eat for lunch?" },
			{
				gateway: {
					id: "gateway_id",
					metadata: { team: "AI", user: 12345, test: true },
				},
			},
		);

		return new Response(aiResp);
	},
};

这篇文档对您有帮助吗?