API でヒューマンフィードバックを追加する

このガイドでは、Cloudflare API を使って AI Gateway のリクエストにヒューマンフィードバックを追加する手順を説明します。関連するリクエストログの取得方法と、API でのフィードバック送信方法を学びます。

ダッシュボードからヒューマンフィードバックを追加する場合は、ヒューマンフィードバックを追加するを参照してください。

1. API トークンを作成する

次の権限を持つ API トークンを作成します。

AI Gateway - Read
AI Gateway - Edit

Account ID を取得します。
その API トークンと Account ID を使い、Cloudflare API に POST リクエストを送信します。

2. `cf-aig-log-id` を取得する

cf-aig-log-id は、フィードバックを追加したい特定のログエントリの一意の識別子です。この識別子を取得する方法を次に示します。

方法 1: リクエストレスポンスで `cf-aig-log-id` を確認する

この方法では、AI Gateway が返すレスポンスのヘッダーから直接 cf-aig-log-id を見つけます。元の API レスポンスにアクセスできる場合、これが最も簡単な方法です。

手順は次のとおりです。

AI Gateway にリクエストを送信する: アプリケーションから AI Gateway へ送るリクエストでかまいません。リクエスト後、レスポンスにはさまざまなメタデータが含まれます。
レスポンスヘッダーを確認する: レスポンスには cf-aig-log-id というヘッダーがあります。これがフィードバック送信に必要な識別子です。

次の例では、cf-aig-log-id は 01JADMCQQQBWH3NXZ5GCRN98DP です。

{
	"status": "success",
	"headers": {
		"cf-aig-log-id": "01JADMCQQQBWH3NXZ5GCRN98DP"
	},
	"data": {
		"response": "Sample response data"
	}
}

方法 2: API（GET リクエスト）で `cf-aig-log-id` を取得する

レスポンス本文に cf-aig-log-id がない場合や、後から参照する必要がある場合は、Cloudflare API でログを照会して取得できます。

GET リクエストを送信してログ一覧を取得し、特定の ID を探します。

Required API token permissions

At least one of the following token permissions is required:

AI Gateway Write
AI Gateway Read

List Gateway Logsbash

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways/$GATEWAY_ID/logs" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
	"result": [
		{
			"id": "01JADMCQQQBWH3NXZ5GCRN98DP",
			"cached": true,
			"created_at": "2019-08-24T14:15:22Z",
			"custom_cost": true,
			"duration": 0,
			"id": "string",
			"metadata": "string",
			"model": "string",
			"model_type": "string",
			"path": "string",
			"provider": "string",
			"request_content_type": "string",
			"request_type": "string",
			"response_content_type": "string",
			"status_code": 0,
			"step": 0,
			"success": true,
			"tokens_in": 0,
			"tokens_out": 0
		}
	]
}

方法 3: バインディングで `cf-aig-log-id` を取得する

バインディングを使って cf-aig-log-id を取得することもできます。手順が簡潔になります。ログ ID を直接取得する例は次のとおりです。

const resp = await env.AI.run(
	"@cf/meta/llama-3-8b-instruct",
	{
		prompt: "tell me a joke",
	},
	{
		gateway: {
			id: "my_gateway_id",
		},
	},
);

const myLogId = env.AI.aiGatewayLogId;

3. PATCH リクエストでフィードバックを送信する

API トークンと cf-aig-log-id の両方を用意したら、PATCH リクエストを送信してフィードバックを提出できます。

Required API token permissions

At least one of the following token permissions is required:

AI Gateway Write

Patch Gateway Logbash

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways/$GATEWAY_ID/logs/$ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"feedback": 1
	}'

否定的なフィードバックの場合は、リクエスト本文を -1 にします。

{
	"feedback": -1
}

4. フィードバックの送信を確認する

フィードバックの送信は、次の 2 つの方法で確認できます。

Cloudflare ダッシュボード ↗ から: AI Gateway の画面で更新されたフィードバックを確認します。
API から: もう一度 GET リクエストを送信し、更新されたログエントリを取得して、フィードバックが記録されていることを確認します。