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

# Weaviate integration guide

> Configure Weaviate's OpenAI vectorizer and generative modules to use SambaStack embeddings and SambaNova chat models.

[Weaviate](https://weaviate.io/) is an open-source vector database that runs vectorization and generation as database modules, so your application code sends text and Weaviate does the rest. Its `text2vec-openai` and `generative-openai` modules accept a `baseURL`, which is the documented route to any OpenAI-compatible endpoint. Pointing both at a SambaStack instance lets Weaviate embed your data and answer questions with SambaNova models.

> [!WARNING]
>
> Embeddings are available on SambaStack only. `E5-Mistral-7B-Instruct` is not available on SambaCloud. See [Implement embeddings features](https://docs.sambanova.ai/docs/en/features/embeddings.md).
>
> On SambaCloud, you can still use Weaviate with your own vectors and a SambaNova chat model. See [Use Weaviate with SambaCloud](#use-weaviate-with-sambacloud).

## Prerequisites

* A SambaStack instance that serves `E5-Mistral-7B-Instruct`, plus the instance's base URL and API key. See [API keys and URLs](https://docs.sambanova.ai/docs/en/get-started/api-keys-urls.md).
* A chat model on that instance. This guide uses `gpt-oss-120b`.
* A running Weaviate server, or a [Weaviate Cloud](https://docs.weaviate.io/cloud) cluster. To run one locally, follow the [Weaviate Docker installation guide](https://docs.weaviate.io/deploy/installation-guides/docker-installation).
* Network access from the Weaviate server to your SambaStack instance. The Weaviate server calls SambaStack, not your Python code, so a Weaviate Cloud cluster cannot reach a SambaStack instance on a private network.
* Python 3.10 or higher.

> [!NOTE]
>
> macOS ships with Python 3.9 and exposes it as `python3` rather than `python`. Check your version with `python3 --version`. If it is below 3.10, install a supported version with [pyenv](https://github.com/pyenv/pyenv), [uv](https://docs.astral.sh/uv/), or `brew install python@3.12` before continuing.

The `text2vec-openai` and `generative-openai` modules must be enabled on your Weaviate server. Weaviate Cloud enables them by default. On a self-hosted server, open `/v1/meta` and check that both appear under `modules`. If they do not, enable them with the `ENABLE_MODULES` environment variable, as described in Weaviate's [module configuration guide](https://docs.weaviate.io/weaviate/configuration/modules).

## Installation and setup

**1. Create a virtual environment**

```bash macOS / Linux theme={}
python3 -m venv .venv
source .venv/bin/activate
```

```powershell Windows theme={}
python -m venv .venv
.venv\Scripts\Activate.ps1
```

**2. Install dependencies**

```bash theme={}
pip install weaviate-client
```

This guide was tested with `weaviate-client` 4.24.1 and Weaviate 1.40.1.

**3. Set your SambaStack base URL and API key**

Do not add `/v1` to the base URL here. Weaviate appends `/v1/embeddings` and `/v1/chat/completions` itself, so a base URL that already ends in `/v1` produces a `404`.

```bash macOS / Linux theme={}
export SAMBANOVA_BASE_URL="your-sambastack-base-url"
export SAMBANOVA_API_KEY="your-sambanova-api-key"
```

```powershell Windows theme={}
$env:SAMBANOVA_BASE_URL="your-sambastack-base-url"
$env:SAMBANOVA_API_KEY="your-sambanova-api-key"
```

## Configure the modules and query

Run the steps in this section in one Python file or session. Each step uses variables from the steps before it.

**1. Connect to Weaviate**

Weaviate sends your SambaNova key to the modules in the `X-OpenAI-Api-Key` header.

```python theme={}
import os
import weaviate

client = weaviate.connect_to_local(
    headers={"X-OpenAI-Api-Key": os.environ["SAMBANOVA_API_KEY"]},
)
```

`connect_to_local` connects to a server on `localhost`. For Weaviate Cloud, set `WEAVIATE_URL` to your cluster URL and `WEAVIATE_API_KEY` to your cluster's API key, then connect with `connect_to_weaviate_cloud` and the same `headers`:

```python theme={}
from weaviate.classes.init import Auth

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=os.environ["WEAVIATE_URL"],
    auth_credentials=Auth.api_key(os.environ["WEAVIATE_API_KEY"]),
    headers={"X-OpenAI-Api-Key": os.environ["SAMBANOVA_API_KEY"]},
)
```

**2. Create a collection that uses SambaNova**

Set `base_url` on both modules, and name the SambaNova models. Weaviate reads the vector size from the model, so you do not set a dimension.

```python theme={}
from weaviate.classes.config import Configure, DataType, Property

base_url = os.environ["SAMBANOVA_BASE_URL"]

if client.collections.exists("SambaNovaDemo"):
    client.collections.delete("SambaNovaDemo")

collection = client.collections.create(
    "SambaNovaDemo",
    properties=[Property(name="text", data_type=DataType.TEXT)],
    vector_config=Configure.Vectors.text2vec_openai(
        base_url=base_url,
        model="E5-Mistral-7B-Instruct",
    ),
    generative_config=Configure.Generative.openai(
        base_url=base_url,
        model="gpt-oss-120b",
    ),
)
```

If a `SambaNovaDemo` collection already exists, the code deletes it first, so each run starts with a clean collection.

`text2vec_openai` handles embeddings and `Generative.openai` handles chat completions. Weaviate calls SambaNova from the server, so the SambaStack instance must be reachable from where Weaviate runs.

**3. Add your documents**

Weaviate embeds each object as it is inserted. You pass text and never handle vectors.

```python theme={}
collection.data.insert_many([
    {"text": "SambaNova builds the SN40L chip, a reconfigurable dataflow unit for fast AI inference."},
    {"text": "Weaviate is an open-source vector database."},
    {"text": "Sourdough bread needs a live starter, flour, water, and salt, and a long slow fermentation."},
    {"text": "The capital of Brazil is Brasilia, which was inaugurated in 1960."},
])
```

**4. Search by meaning**

```python theme={}
from weaviate.classes.query import MetadataQuery

response = collection.query.near_text(
    query="Which chip does SambaNova make?",
    limit=2,
    return_metadata=MetadataQuery(distance=True),
)

for obj in response.objects:
    print(f"{obj.metadata.distance:.3f} {obj.properties['text']}")
```

Lower distance means a closer match. The closest match is the passage about the SN40L chip, at a cosine distance of about 0.33. The next closest is about 0.43.

**5. Answer with a SambaNova chat model**

Weaviate retrieves the closest objects and passes them to the generative module in one call.

```python theme={}
response = collection.generate.near_text(
    query="Which chip does SambaNova make?",
    limit=2,
    grouped_task="Which chip does SambaNova make? Answer using only these passages.",
)
print(response.generative.text)
```

The model answers that SambaNova makes the SN40L chip.

**6. Delete the collection and close the connection**

```python theme={}
client.collections.delete("SambaNovaDemo")
client.close()
```

## Use Weaviate with SambaCloud

SambaCloud does not serve embeddings, so embed the text yourself with a local model and let Weaviate's generative module call SambaCloud for answers. Install FastEmbed, and set `SAMBANOVA_BASE_URL` to `https://api.sambanova.ai`.

```bash theme={}
pip install fastembed
```

```python theme={}
import os
import weaviate
from fastembed import TextEmbedding
from weaviate.classes.config import Configure, DataType, Property
from weaviate.classes.data import DataObject

local_model = TextEmbedding()

def embed(texts):
    return [vector.tolist() for vector in local_model.embed(texts)]

client = weaviate.connect_to_local(
    headers={"X-OpenAI-Api-Key": os.environ["SAMBANOVA_API_KEY"]},
)

if client.collections.exists("SambaNovaDemo"):
    client.collections.delete("SambaNovaDemo")

collection = client.collections.create(
    "SambaNovaDemo",
    properties=[Property(name="text", data_type=DataType.TEXT)],
    vector_config=Configure.Vectors.self_provided(),
    generative_config=Configure.Generative.openai(
        base_url=os.environ["SAMBANOVA_BASE_URL"],
        model="gpt-oss-120b",
    ),
)

docs = [
    "SambaNova builds the SN40L chip, a reconfigurable dataflow unit for fast AI inference.",
    "Weaviate is an open-source vector database.",
]
collection.data.insert_many(
    [DataObject(properties={"text": d}, vector=v) for d, v in zip(docs, embed(docs))]
)

question = "Which chip does SambaNova make?"
response = collection.generate.near_vector(
    near_vector=embed([question])[0],
    limit=2,
    grouped_task=f"{question} Answer using only these passages.",
)
print(response.generative.text)

client.collections.delete("SambaNovaDemo")
client.close()
```

## Additional resources

> [card] [Weaviate documentation](https://docs.weaviate.io/weaviate)
>
> Official guides covering collections, search, and deployment.

> [card] [OpenAI embeddings in Weaviate](https://docs.weaviate.io/weaviate/model-providers/openai/embeddings)
>
> Reference for the `text2vec-openai` module and its parameters.

> [card] [OpenAI generative AI in Weaviate](https://docs.weaviate.io/weaviate/model-providers/openai/generative)
>
> Reference for the `generative-openai` module and its parameters.

> [card] [Implement embeddings features](https://docs.sambanova.ai/docs/en/features/embeddings.md)
>
> How to use SambaNova embedding models on SambaStack.

## Troubleshooting

> [accordion] KeyError: 'SAMBANOVA\_BASE\_URL'
>
> An environment variable is not set in the shell you run Python from. The error names the missing variable, such as `SAMBANOVA_BASE_URL` or `SAMBANOVA_API_KEY`. Set it as shown in [Installation and setup](#installation-and-setup), then run the code again from the same shell. For Weaviate Cloud, also set `WEAVIATE_URL` and `WEAVIATE_API_KEY`.

> [accordion] failed to parse vectorization response (status 404)
>
> The base URL ends in `/v1`. Weaviate adds `/v1/embeddings` to the base URL, so it ends up calling `/v1/v1/embeddings`. Set `base_url` to your SambaStack base URL without `/v1`, then recreate the collection.

> [accordion] API Key: no api key found neither in request header: X-Openai-Api-Key
>
> The connection has no key to send to the module. Pass `headers={"X-OpenAI-Api-Key": ...}` to `connect_to_local` or `connect_to_weaviate_cloud`, and check that `SAMBANOVA_API_KEY` is exported in the shell you run Python from.

> [accordion] connection to: OpenAI API failed with status: 401
>
> The key does not match the base URL. Use the key issued for your SambaStack instance.

> [accordion] connection to: OpenAI API failed with status: 404 ... model does not exist
>
> The instance does not serve the model named in the collection, or your key cannot access it. List the models the instance serves:
>
> ```bash macOS / Linux theme={}
> curl -H "Authorization: Bearer $SAMBANOVA_API_KEY" "$SAMBANOVA_BASE_URL/v1/models"
> ```
>
> ```powershell Windows theme={}
> curl.exe -H "Authorization: Bearer $env:SAMBANOVA_API_KEY" "$env:SAMBANOVA_BASE_URL/v1/models"
> ```
>
> SambaCloud does not serve embeddings. See [Use Weaviate with SambaCloud](#use-weaviate-with-sambacloud).

> [accordion] 422: class name SambaNovaDemo already exists
>
> The code above deletes an existing `SambaNovaDemo` collection first. If you removed that check, delete it with `client.collections.delete("SambaNovaDemo")`.