> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddings and reranking

> Build semantic search, knowledge bases, and RAG workflows with embeddings and reranking.

Embeddings convert text into vectors. Reranking scores candidate documents against a query. Together they are the core building blocks for semantic search, knowledge bases, and retrieval-augmented generation.

## Embeddings

An embedding is a list of numbers that represents the meaning of text. Text with similar meaning tends to have similar vectors, which lets you search by meaning instead of exact keywords.

Use `/v1/embeddings` to create vectors:

```json theme={null}
{
  "model": "text-embedding-3-small",
  "input": "Moxus AI is a unified LLM API gateway."
}
```

| Parameter         | Description                                         |
| ----------------- | --------------------------------------------------- |
| `model`           | Embedding model name                                |
| `input`           | A string or an array of strings                     |
| `encoding_format` | Optional output format, usually `float` or `base64` |

Example response:

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.023, -0.015, 0.042, -0.008]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}
```

## Python example

```python theme={null}
from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://moxus.ai/v1")

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Moxus AI is a unified LLM API gateway.",
)

vector = response.data[0].embedding
print(f"Vector dimensions: {len(vector)}")
print(vector[:5])
```

## Batch embeddings

```python theme={null}
texts = [
    "Moxus AI supports multiple providers.",
    "OpenAI provides GPT models.",
    "Claude is developed by Anthropic.",
]

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts,
)

for index, item in enumerate(response.data):
    print(index, len(item.embedding))
```

## Similarity search

After you create vectors, store them in a vector database such as Milvus, Qdrant, Chroma, Pinecone, or pgvector. At query time, embed the user question and search for nearest vectors.

```python theme={null}
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
```

## Reranking

Reranking takes a query and candidate documents, then returns a relevance score for each candidate. It is commonly used after vector search to improve result quality.

```json theme={null}
{
  "model": "rerank-model",
  "query": "How does Moxus AI billing work?",
  "documents": [
    "Moxus AI bills by token usage.",
    "Moxus AI supports multiple model providers.",
    "Python is a programming language."
  ],
  "top_n": 2
}
```

Example response:

```json theme={null}
{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.92,
      "document": "Moxus AI bills by token usage."
    },
    {
      "index": 1,
      "relevance_score": 0.65,
      "document": "Moxus AI supports multiple model providers."
    }
  ]
}
```

The exact endpoint and response shape can vary by provider. Use the model detail page as the source of truth for supported parameters.

## Typical RAG flow

1. Split source documents into chunks.
2. Create embeddings for each chunk.
3. Store vectors and metadata in a vector database.
4. Embed the user query.
5. Retrieve the most similar chunks.
6. Optionally rerank the retrieved chunks.
7. Send the best context to a chat model for the final answer.

## Practical guidance

* Choose an embedding model that matches your language and domain.
* Keep chunk sizes consistent and include useful metadata.
* Rerank only the top candidates to control cost and latency.
* Monitor token usage in [dashboard and usage](/en/platform/dashboard-and-usage).

## Next steps

* [SDK integration](/en/integrations/sdks)
* [Third-party clients](/en/integrations/clients)