Cluster API

The POST https://llmfoundry.straive.com/cluster API groups documents (using KMeans) with the embeddings dot-product as the distance between documents. It accepts a JSON body with:

  • docs: List of strings or objects containing {type, value}. type can be text or image. Value can be the text or a base-64 encoded image. Examples:
    • ["King", "Queen"]
    • [{"type": "text", "value": "King"}, {"type": "text", "value": "Queen"]
    • [{"type": "image", "value": "data:image/jpeg;base64,..."}, {"type": "image", "value": "data:image/png;base64,..."}, ]
  • model: Optional string. Model used for embeddings. Default is text-embedding-3-small. Can be
    • text-embedding-3-small (medium accuracy, low cost)
    • text-embedding-3-large (high accuracy higher cost)
    • text-embedding-ada-002 (low accuracy, medium cost -- avoid)
    • multimodalembedding@001 (for image: JPG, PNG, BMP, GIF, video: AVI, FLV, MKV, MOV, MP4, MPEG, MPG, WEBM, WMV, and text)
  • n: Optional number of clusters. Defaults to sqrt(len(docs)/2).
  • precision: Optional integer. Defaults to 5. Number of decimal places in the similarity score.

Example:

{
  "model": "text-embedding-3-small",
  "docs": ["Apple", "Orange", "42"],
  "n": 2,
  "precision": 5
}

It returns a JSON object with:

  • model: The model used
  • cluster: A list of cluster indices for each document (0, 1, ... n)
  • score: The silhouette score of the clustering. Higher is better.
  • scores: The silhouette scores of each cluster. +1 means well clustered. Near 0 indicates high overlap. -1 means misclustered.
  • tokens: The number of tokens used
{
  "cluster": [0, 0, 1],
  "score": 0.09092,
  "scores": [0.1433, 0.12945, 0.0],
  "model": "text-embedding-3-small",
  "tokens": 3
}

Curl

curl -X POST https://llmfoundry.straive.com/cluster \
    -H "Authorization: Bearer $LLMFOUNDRY_TOKEN:my-test-project" \
    -H "Content-Type: application/json" \
    -d '{"docs": ["Apple", "Orange", "42"], "n": 3}'

Python requests

import os
import requests  # Or replace requests with httpx

response = requests.post(
    "https://llmfoundry.straive.com/cluster",
    headers={"Authorization": f"Bearer {os.environ['LLMFOUNDRY_TOKEN']}:my-test-project"},
    json={"docs": ["Apple", "Orange", "42"], "n": 2}
)
print(response.json())