カスタムメタデータ

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 の保存を保証します。リクエストにすでにカスタムメタデータが 5 件ある場合、AI Gateway は末尾のカスタムエントリを削除して cf.user_id を保存することがあります。サービストークンのリクエストと、ユーザー subject がないリクエストには、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);
	},
};