← Cloudflare AI Gateway / ai-gateway / observability

Vlastní metadata

Vlastní metadata v AI Gateway vám umožňují označovat požadavky ID uživatelů nebo jinými identifikátory, což zlepšuje sledování a analýzu vašich požadavků. Hodnoty metadat mohou být řetězce, čísla nebo booleovské hodnoty a zobrazují se ve vašich protokolech, díky čemuž lze data snadno vyhledávat a filtrovat.

• Custom Tagging: Přidejte do svých požadavků ID uživatelů, názvy týmů, testovací indikátory a další relevantní informace.
• Rozšířené protokolování: Metadata se zobrazují ve vašich protokolech, což umožňuje podrobnou kontrolu a řešení problémů.
• Vyhledávání a filtrování: Používejte metadata k efektivnímu vyhledávání a filtrování zaznamenaných požadavků.

• Řetězec
• Číslo
• Boolean

Klíče metadat, které začínají na cf. jsou vyhrazeny pro metadata přidaná Cloudflare. Neposílejte vlastní cf.* klíče metadat. AI Gateway odstraňuje zákazníkem zadané cf.* klíče před uložením metadat požadavku.

Když požadavek dorazí do AI Gateway přes vlastní doménu chráněnou Cloudflare Access, AI Gateway přidá ID ověřeného uživatele Access do metadat požadavku jako cf.user_id. Tato hodnota představuje ověřený Access JWT sub claim, nikoli e-mailovou adresu uživatele.

AI Gateway zaručuje, že cf.user_id se uloží, pokud je k dispozici platné ID uživatele Access. Pokud požadavek již obsahuje pět vlastních položek metadat, AI Gateway může odstranit poslední vlastní položku, aby cf.user_id lze uložit. Požadavky se service tokenem a požadavky bez subjektu uživatele nezískávají cf.user_id metadata.

Chcete-li do požadavku zahrnout custom metadata pomocí 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?"}]}'

Chcete-li do požadavku zahrnout custom metadata pomocí 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);
		}
	},
};

Chcete-li do požadavku zahrnout custom metadata pomocí 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);
	},
};