← Cloudflare AI Gateway / ai-gateway / observability

Пользовательские метаданные

Пользовательские метаданные в AI Gateway позволяют помечать запросы идентификаторами пользователей или другими метками, что улучшает отслеживание и анализ ваших запросов. Значения метаданных могут быть строками, числами или булевыми значениями и отображаются в логах, что упрощает поиск и фильтрацию данных.

• Custom Tagging: добавляйте в свои запросы ID пользователей, названия команд, тестовые метки и другую релевантную информацию.
• Расширенное логирование: Метаданные отображаются в ваших журналах, что позволяет детально анализировать запросы и устранять неполадки.
• Поиск и фильтрация: Используйте метаданные для эффективного поиска и фильтрации журналируемых запросов.

• String
• Число
• Boolean

Ключи метаданных, начинающиеся с cf. зарезервированы для метаданных, добавляемых Cloudflare. Не отправляйте собственные cf.* ключи метаданных. AI Gateway удаляет предоставленные клиентом cf.* ключи перед сохранением метаданных запроса.

Когда запрос поступает в AI Gateway через пользовательский домен, защищённый Cloudflare Access, AI Gateway добавляет ID аутентифицированного пользователя Access в метаданные запроса как cf.user_id. Это значение представляет собой проверенный Access JWT sub claim, а не адрес электронной почты пользователя.

AI Gateway гарантирует, что cf.user_id сохраняется, если присутствует действительный ID пользователя Access. Если в запросе уже есть пять пользовательских записей метаданных, AI Gateway может удалить последнюю из них, чтобы cf.user_id можно сохранить. Запросы с токеном службы и запросы без субъекта пользователя не получают cf.user_id метаданные.

Чтобы включить Custom Metadata в свой запрос с помощью 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?"}]}'

Чтобы включить Custom Metadata в свой запрос с помощью 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);
		}
	},
};

Чтобы включить Custom Metadata в свой запрос с помощью 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);
	},
};