Text Similarity

Compare two text strings for semantic similarity using Workers AI embeddings and cosine similarity. Returns a score between 0 and 1.

FeaturesCopy Anchor Link

• Compare two text strings for semantic similarity (score 0–1)
• Workers AI embeddings via @cf/baai/bge-base-en-v1.5
• Cosine similarity computed at the edge
• Stateless GET API with text1 and text2 query parameters

API ReferenceCopy Anchor Link

GET /similarityCopy Anchor Link

Computes the cosine similarity between embeddings of two text inputs.

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/similarity?text1=hello%20world&text2=hello%20there"

Success ResponseCopy Anchor Link

text1 string

The first input text

text2 string

The second input text

similarity number

Cosine similarity score between 0 and 1 (higher means more similar)

{
  "text1": "hello world",
  "text2": "hello there",
  "similarity": 0.82
}

Error ResponseCopy Anchor Link

{
  "error": "Missing or invalid query parameter: text1",
  "code": "INVALID_TEXT1"
}

Error CodesCopy Anchor Link

• 400 - Missing or invalid text1 (INVALID_TEXT1)
• 400 - Missing or invalid text2 (INVALID_TEXT2)
• 502 - Workers AI model run failed (AI_ERROR)

Use CasesCopy Anchor Link

• Detect duplicate or near-duplicate content at the edge
• Rank search results or FAQ matches by semantic relevance
• Learn Workers AI embedding models and vector similarity
• Build lightweight deduplication or matching APIs without a vector database

LimitationsCopy Anchor Link

• Workers AI is subject to usage limits by plan
• Each input string length is capped
• Compares two strings only; no corpus or vector database search

Use in your projectCopy Anchor Link

import type { Env } from "../types/env";import { AI_MODEL } from "../constants/defaults";type EmbeddingResult = {  data?: number[][];};export function cosineSimilarity(a: number[], b: number[]): number {  if (a.length !== b.length || a.length === 0) return 0;  let dot = 0;  let normA = 0;  let normB = 0;  for (let i = 0; i < a.length; i++) {    dot += a[i] * b[i];    normA += a[i] * a[i];    normB += b[i] * b[i];  }  const denom = Math.sqrt(normA) * Math.sqrt(normB);  if (denom === 0) return 0;  const raw = dot / denom;  return Math.max(0, Math.min(1, raw));}export async function computeSimilarity(env: Env, text1: string, text2: string): Promise<number> {  const out = (await env.AI.run(AI_MODEL, { text: [text1, text2] })) as EmbeddingResult;  const vectors = out.data;  if (!vectors || vectors.length < 2) {    throw new Error("Embedding model returned insufficient vectors");  }  return cosineSimilarity(vectors[0], vectors[1]);}

DeploymentCopy Anchor Link

curl "https://your-worker.workers.dev/similarity?text1=hello&text2=hi"

Local DevelopmentCopy Anchor Link

cd apps/experiments/text-similarity
npm install
npm run dev

Test locally:

curl "http://localhost:8787/similarity?text1=hello&text2=hi"

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• Workers AI - @cf/baai/bge-base-en-v1.5 text embedding model