python-sdk/docs/content/docs/embeddings.mdx

---
title: Embeddings
description: Generate text embeddings with the Hanzo API
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

# Embeddings

The Embeddings API generates vector representations of text that can be used for semantic search, clustering, and similarity comparisons.

## Basic Usage

```python
from hanzoai import Hanzo

client = Hanzo()

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

embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}")
```

## Multiple Inputs

Generate embeddings for multiple texts at once:

```python
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=[
        "First document",
        "Second document",
        "Third document"
    ]
)

for i, data in enumerate(response.data):
    print(f"Document {i}: {len(data.embedding)} dimensions")
```

## Embedding Models

| Model | Dimensions | Description |
|-------|------------|-------------|
| `text-embedding-3-small` | 1536 | Fast, efficient |
| `text-embedding-3-large` | 3072 | Higher quality |
| `text-embedding-ada-002` | 1536 | Legacy model |

```python
# High quality embeddings
response = client.embeddings.create(
    model="text-embedding-3-large",
    input="Important document"
)
```

## Dimension Reduction

Reduce embedding dimensions for efficiency:

```python
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Hello, world!",
    dimensions=256  # Reduce from 1536 to 256
)

print(f"Dimensions: {len(response.data[0].embedding)}")  # 256
```

## Semantic Search

Use embeddings for semantic search:

```python
import numpy as np
from hanzoai import Hanzo

client = Hanzo()

def get_embedding(text):
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

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

# Create document embeddings
documents = [
    "Python is a programming language",
    "JavaScript runs in browsers",
    "Machine learning uses algorithms",
    "Cats are furry animals"
]

doc_embeddings = [get_embedding(doc) for doc in documents]

# Search
query = "coding languages"
query_embedding = get_embedding(query)

# Find most similar
similarities = [cosine_similarity(query_embedding, doc_emb) for doc_emb in doc_embeddings]

for doc, score in sorted(zip(documents, similarities), key=lambda x: x[1], reverse=True):
    print(f"{score:.3f}: {doc}")
```

## Batch Processing

Process large datasets efficiently:

```python
from hanzoai import Hanzo

client = Hanzo()

def batch_embed(texts, batch_size=100):
    """Embed texts in batches."""
    embeddings = []

    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]
        response = client.embeddings.create(
            model="text-embedding-3-small",
            input=batch
        )
        embeddings.extend([d.embedding for d in response.data])

    return embeddings

# Embed 1000 documents
documents = ["Document " + str(i) for i in range(1000)]
all_embeddings = batch_embed(documents)
```

## Async Embeddings

Generate embeddings asynchronously:

```python
import asyncio
from hanzoai import AsyncHanzo

async def main():
    client = AsyncHanzo()

    response = await client.embeddings.create(
        model="text-embedding-3-small",
        input="Hello, world!"
    )

    print(f"Dimensions: {len(response.data[0].embedding)}")

asyncio.run(main())
```

## Parallel Async Embedding

```python
import asyncio
from hanzoai import AsyncHanzo

async def embed_document(client, text):
    response = await client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

async def main():
    client = AsyncHanzo()

    documents = [
        "First document",
        "Second document",
        "Third document"
    ]

    # Embed all documents in parallel
    embeddings = await asyncio.gather(*[
        embed_document(client, doc) for doc in documents
    ])

    print(f"Generated {len(embeddings)} embeddings")

asyncio.run(main())
```

## Response Object

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

print(response.model)                    # Model used
print(response.usage.prompt_tokens)      # Tokens used
print(response.usage.total_tokens)       # Total tokens
print(response.data[0].index)            # Input index
print(response.data[0].embedding[:5])    # First 5 dimensions
```

## Storage with Vector Databases

Store embeddings in vector databases:

<Tabs items={['Pinecone', 'Qdrant', 'Weaviate']}>
  <Tab value="Pinecone">
    ```python
    import pinecone
    from hanzoai import Hanzo

    client = Hanzo()
    pinecone.init(api_key="your-key")
    index = pinecone.Index("my-index")

    # Embed and store
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input="Document content"
    )

    index.upsert([
        ("doc-1", response.data[0].embedding, {"text": "Document content"})
    ])
    ```
  </Tab>
  <Tab value="Qdrant">
    ```python
    from qdrant_client import QdrantClient
    from qdrant_client.models import PointStruct
    from hanzoai import Hanzo

    client = Hanzo()
    qdrant = QdrantClient(":memory:")

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

    qdrant.upsert(
        collection_name="documents",
        points=[
            PointStruct(
                id=1,
                vector=response.data[0].embedding,
                payload={"text": "Document content"}
            )
        ]
    )
    ```
  </Tab>
  <Tab value="Weaviate">
    ```python
    import weaviate
    from hanzoai import Hanzo

    client = Hanzo()
    weaviate_client = weaviate.Client("http://localhost:8080")

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

    weaviate_client.data_object.create(
        class_name="Document",
        data_object={"text": "Document content"},
        vector=response.data[0].embedding
    )
    ```
  </Tab>
</Tabs>

## Next Steps

- [Models](/docs/python-sdk/models) - List available models
- [Files](/docs/python-sdk/files) - Upload and manage files
- [Chat](/docs/python-sdk/chat) - Generate chat completions