Refactor semantic search gateway ID references to use embedding gateway ID

Updated the codebase to replace instances of `CLOUDFLARE_AI_GATEWAY_ID` with `CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID` in the semantic search functionality. This change clarifies the distinction between the two gateway IDs and ensures that both runtime queries and indexing jobs utilize the correct embedding gateway. Additionally, updated related documentation and test cases to reflect this change.

Author: kentcdodds

.env.example

@@ -105,9 +105,9 @@ CLOUDFLARE_API_TOKEN=MOCK_CLOUDFLARE_API_TOKEN
 CLOUDFLARE_VECTORIZE_INDEX=MOCK_CLOUDFLARE_VECTORIZE_INDEX
 # Route Workers AI requests through Cloudflare AI Gateway (gateway name/id)
 CLOUDFLARE_AI_GATEWAY_ID=MOCK_CLOUDFLARE_AI_GATEWAY_ID
-# Optional: indexing/batch embedding jobs can use a different AI Gateway (for
-# example, without guardrails). Runtime user search queries still use
-# CLOUDFLARE_AI_GATEWAY_ID. Falls back to CLOUDFLARE_AI_GATEWAY_ID when omitted.
+# Optional: embedding requests can use a different AI Gateway (for example,
+# without guardrails). Used by semantic-search embeddings for both runtime
+# queries and indexing jobs. Falls back to CLOUDFLARE_AI_GATEWAY_ID when omitted.
 CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID=MOCK_CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID
 # AI Gateway Authenticated Gateway token (sent as `cf-aig-authorization`)
 CLOUDFLARE_AI_GATEWAY_AUTH_TOKEN=MOCK_CLOUDFLARE_AI_GATEWAY_AUTH_TOKEN

app/utils/__tests__/semantic-search.server.test.ts

@@ -21,7 +21,7 @@ vi.mock('#app/utils/semantic-search-presentation.server.ts', () => ({
 
 import { semanticSearchKCD } from '../semantic-search.server.ts'
 
-test('semanticSearchKCD routes user query embeddings through CLOUDFLARE_AI_GATEWAY_ID', async () => {
+test('semanticSearchKCD routes user query embeddings through CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID', async () => {
 	using ignoredEnv = setEnv({
 		CLOUDFLARE_ACCOUNT_ID: 'cf-account',
 		CLOUDFLARE_API_TOKEN: 'cf-token',
@@ -70,8 +70,8 @@ test('semanticSearchKCD routes user query embeddings through CLOUDFLARE_AI_GATEW
 			.find((url) => url.includes('/workers-ai/'))
 
 		expect(embeddingRequestUrl).toBeDefined()
-		expect(embeddingRequestUrl).toContain('/runtime-search-gateway/')
-		expect(embeddingRequestUrl).not.toContain('/indexing-only-gateway/')
+		expect(embeddingRequestUrl).toContain('/indexing-only-gateway/')
+		expect(embeddingRequestUrl).not.toContain('/runtime-search-gateway/')
 	} finally {
 		fetchSpy.mockRestore()
 	}

app/utils/env.server.ts

@@ -68,8 +68,8 @@ const schemaBase = z.object({
 	/** AI Gateway "id" is the gateway name you create in Cloudflare. */
 	CLOUDFLARE_AI_GATEWAY_ID: nonEmptyString,
 	/**
-	 * Optional indexing/batch embedding AI Gateway id.
-	 * Runtime user search queries continue to use `CLOUDFLARE_AI_GATEWAY_ID`.
+	 * Optional embedding AI Gateway id.
+	 * Used by semantic-search embeddings (runtime queries + indexing jobs).
 	 * Falls back to `CLOUDFLARE_AI_GATEWAY_ID` when omitted.
 	 */
 	CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID: z.string().trim().optional(),
@@ -184,9 +184,9 @@ export type Env = Omit<
 	 */
 	CLOUDFLARE_AI_CALL_KENT_TRANSCRIPT_FORMAT_MODEL: string
 	/**
-	 * Indexing/batch embedding jobs can be routed through a separate gateway
-	 * (for example, with guardrails disabled). Runtime user search queries
-	 * should use `CLOUDFLARE_AI_GATEWAY_ID`.
+	 * Embedding calls can be routed through a separate gateway (for example, with
+	 * guardrails disabled). This is used by semantic-search embeddings for both
+	 * runtime user queries and indexing jobs.
 	 */
 	CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID: string
 	/** Derived from CLOUDFLARE_ACCOUNT_ID when not explicitly set. */

app/utils/semantic-search.server.ts

@@ -184,7 +184,7 @@ function getRequiredSemanticSearchEnv() {
 	return {
 		accountId: env.CLOUDFLARE_ACCOUNT_ID,
 		apiToken: env.CLOUDFLARE_API_TOKEN,
-		gatewayId: env.CLOUDFLARE_AI_GATEWAY_ID,
+		embeddingGatewayId: env.CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID,
 		gatewayAuthToken: env.CLOUDFLARE_AI_GATEWAY_AUTH_TOKEN,
 		indexName: env.CLOUDFLARE_VECTORIZE_INDEX,
 		embeddingModel: env.CLOUDFLARE_AI_EMBEDDING_MODEL,
@@ -227,21 +227,21 @@ async function cloudflareFetch(
 async function getEmbedding({
 	accountId,
 	apiToken,
-	gatewayId,
+	embeddingGatewayId,
 	gatewayAuthToken,
 	model,
 	text,
 }: {
 	accountId: string
 	apiToken: string
-	gatewayId: string
+	embeddingGatewayId: string
 	gatewayAuthToken: string
 	model: string
 	text: string
 }) {
 	const url = getWorkersAiRunUrl({
 		accountId,
-		gatewayId,
+		gatewayId: embeddingGatewayId,
 		model,
 	})
 	const res = await fetch(url, {
@@ -502,7 +502,7 @@ export async function semanticSearchKCD({
 	const {
 		accountId,
 		apiToken,
-		gatewayId,
+		embeddingGatewayId,
 		gatewayAuthToken,
 		indexName,
 		embeddingModel,
@@ -539,7 +539,7 @@ export async function semanticSearchKCD({
 			const vector = await getEmbedding({
 				accountId,
 				apiToken,
-				gatewayId,
+				embeddingGatewayId,
 				gatewayAuthToken,
 				model: embeddingModel,
 				text: cleanedQuery,

other/semantic-search/readme.md

@@ -24,7 +24,7 @@ and shared utilities.
 - `CLOUDFLARE_API_TOKEN`
 - `CLOUDFLARE_VECTORIZE_INDEX`
 - `CLOUDFLARE_AI_EMBEDDING_MODEL` (optional; defaults in code)
-- `CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID` (optional; indexers only; defaults to `CLOUDFLARE_AI_GATEWAY_ID`)
+- `CLOUDFLARE_AI_EMBEDDING_GATEWAY_ID` (optional; used by semantic-search embeddings for runtime queries + indexers; defaults to `CLOUDFLARE_AI_GATEWAY_ID`)
 
 - `R2_BUCKET`