X Enterprises
fastify-x-ai

createEmbedding / similarity

Create single or batch text embeddings for semantic search and RAG, plus cosine similarity scoring.

createEmbedding / similarity

createEmbedding generates vector embeddings for one or many text inputs, using the AI SDK's embed (single) or embedMany (batch) under the hood. similarity wraps cosineSimilarity for ranking or deduplication.

Signatures

fastify.xai.createEmbedding(params: EmbeddingParams): Promise<EmbeddingResult>

// Single text
interface EmbeddingParams {
  text?: string            // one of text/texts required
  texts?: string[]         // one of text/texts required
  provider?: "openai" | "google"
  model?: string
}

// Returns { embedding, usage } for single text
// Returns { embeddings, usage } for texts array
type EmbeddingResult =
  | { embedding: number[]; usage: UsageObject }
  | { embeddings: number[][]; usage: UsageObject }

fastify.xai.similarity(a: number[], b: number[]): number

Params — createEmbedding

NameTypeRequiredDescription
textstringOne of text/textsSingle text to embed
textsstring[]One of text/textsMultiple texts to embed in one call
providerstringNo"openai" (default) or "google"
modelstringNoEmbedding model; defaults to text-embedding-3-small (OpenAI) or text-embedding-004 (Google)

Params — similarity

NameTypeRequiredDescription
anumber[]YesFirst embedding vector
bnumber[]YesSecond embedding vector

Returns

createEmbedding — single input: { embedding: number[], usage }. Batch input: { embeddings: number[][], usage }.

similarity — number in the range –1 to 1. 1 = identical, 0 = orthogonal, –1 = opposite.

Throws

ErrorWhen
xAI createEmbedding: Either 'text' or 'texts' is requiredNeither text nor texts provided
xAI: Provider '…' not configuredSpecified provider has no API key

Examples

Single embedding

const { embedding, usage } = await fastify.xai.createEmbedding({
  text: "semantic search query",
});

console.log(embedding.length); // 1536 (text-embedding-3-small)
console.log(usage);            // { promptTokens: 3, totalTokens: 3 }

Batch embeddings + similarity ranking

fastify.post("/search", async (request, reply) => {
  const { query, documents } = request.body;

  // Embed query and all documents in one call
  const { embeddings } = await fastify.xai.createEmbedding({
    texts: [query, ...documents],
  });

  const [queryEmbedding, ...docEmbeddings] = embeddings;

  // Rank documents by similarity to query
  const ranked = documents
    .map((doc, i) => ({
      doc,
      score: fastify.xai.similarity(queryEmbedding, docEmbeddings[i]),
    }))
    .sort((a, b) => b.score - a.score);

  return { results: ranked };
});

Google embedding model

const { embedding } = await fastify.xai.createEmbedding({
  text: "Nuxt layer architecture patterns",
  provider: "google",
  model: "text-embedding-004",
});

See Also

AI Context

package: "@xenterprises/fastify-x-ai"
methods: fastify.xai.createEmbedding(params) — also exposes similarity(a, b) helper
use-when: Create single or batch vector embeddings for semantic search, RAG, or clustering
params: text (single string) or texts (array of strings), model, provider
returns: { embedding (number[]) | embeddings (number[][]), usage }; similarity(a, b) → cosine similarity number

complete

Simple text completion — accepts a prompt string and returns the generated text directly.

generate

Full-control text generation with prompt or message history, tool calling, and per-call model overrides.

Copyright © 2026