# Text Similarity (/docs/experiments/text-similarity)



Compare two text strings for semantic similarity using [Workers AI](https://developers.cloudflare.com/workers-ai/) embeddings and cosine similarity. Returns a score between 0 and 1.

## Features [#features]

* 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 Reference [#api-reference]

### GET /similarity [#get-similarity]

Computes the cosine similarity between embeddings of two text inputs.

<TypeTable
  type="{
  text1: {
    description: &#x22;First text to compare (max 10,000 characters)&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  text2: {
    description: &#x22;Second text to compare (max 10,000 characters)&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
}"
/>

#### Example Request [#example-request]

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

#### Success Response [#success-response]

**`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)

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

#### Error Response [#error-response]

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

#### Error Codes [#error-codes]

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

## Use Cases [#use-cases]

* 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

## Limitations [#limitations]

* Workers AI is subject to [usage limits](https://developers.cloudflare.com/workers-ai/platform/limits/) by plan
* Each input string length is capped
* Compares two strings only; no corpus or vector database search

## Deployment [#deployment]

<Steps>
  <Step>
    ### Click the deploy button [#click-the-deploy-button]

    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/text-similarity)
  </Step>

  <Step>
    ### Deploy [#deploy]

    Enable the **Workers AI** binding (`AI`) in your Worker settings. The deploy button configures this automatically via `wrangler.json`. Requires a Cloudflare account with Workers AI enabled.
  </Step>

  <Step>
    ### Test your deployment [#test-your-deployment]

    ```bash
    curl "https://your-worker.workers.dev/similarity?text1=hello&text2=hi"
    ```
  </Step>
</Steps>

## Local Development [#local-development]

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

Test locally:

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

## Cloudflare Features Used [#cloudflare-features-used]

* **[Workers](https://developers.cloudflare.com/workers/)** - Edge compute runtime
* **[Workers AI](https://developers.cloudflare.com/workers-ai/)** - `@cf/baai/bge-base-en-v1.5` text embedding model