> ## 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

> Weaviate の OpenAI ベクトル化モジュールと生成モジュールを設定し、SambaStack の Embedding と SambaNova のチャットモデルを利用します。

[Weaviate](https://weaviate.io/) は、ベクトル化と生成をデータベースモジュールとして実行するオープンソースのベクトル DB です。アプリケーションコードはテキストを送るだけで、残りの処理は Weaviate が行います。`text2vec-openai` モジュールと `generative-openai` モジュールは `baseURL` を受け付けます。これは、任意の OpenAI 互換エンドポイントに接続するための、公式ドキュメントに記載された方法です。両モジュールの接続先を SambaStack インスタンスに向けることで、Weaviate によるデータの埋め込みと質問への回答を、SambaNova のモデルで行えます。

> [!WARNING]
>
> Embedding は SambaStack のみで提供されています。`E5-Mistral-7B-Instruct` は SambaCloud では利用できません。[Embedding (埋め込み) 機能の実装](https://docs.sambanova.ai/docs/ja/features/embeddings.md) をご参照ください。
>
> SambaCloud でも、自分で用意したベクトルと SambaNova のチャットモデルを組み合わせて Weaviate を利用できます。[SambaCloud での Weaviate の利用](#sambacloud-での-weaviate-の利用) をご参照ください。

## 前提条件

* `E5-Mistral-7B-Instruct` をサービングしている SambaStack インスタンスと、そのインスタンスのベース URL および API キー。[API キーと URL](https://docs.sambanova.ai/docs/ja/get-started/api-keys-urls.md) をご参照ください。
* 同インスタンス上のチャットモデル。本ガイドでは `gpt-oss-120b` を使用します。
* 稼働中の Weaviate サーバー、または [Weaviate Cloud](https://docs.weaviate.io/cloud) のクラスター。ローカルで実行する場合は、[Weaviate の Docker インストールガイド](https://docs.weaviate.io/deploy/installation-guides/docker-installation) に従ってください。
* Weaviate サーバーから SambaStack インスタンスへのネットワークアクセス。SambaStack を呼び出すのは Python コードではなく Weaviate サーバーであるため、Weaviate Cloud のクラスターからプライベートネットワーク上の SambaStack インスタンスには到達できません。
* Python 3.10 以上。

> [!NOTE]
>
> macOS には Python 3.9 が同梱されており、`python` ではなく `python3` として提供されます。`python3 --version` でバージョンを確認してください。3.10 未満の場合は、続行する前に [pyenv](https://github.com/pyenv/pyenv)、[uv](https://docs.astral.sh/uv/)、または `brew install python@3.12` で対応バージョンをインストールしてください。

お使いの Weaviate サーバーで、`text2vec-openai` モジュールと `generative-openai` モジュールが有効になっている必要があります。Weaviate Cloud では、デフォルトで有効です。セルフホストのサーバーでは、`/v1/meta` を開き、`modules` の下に両方が表示されることを確認してください。表示されない場合は、Weaviate の [モジュール設定ガイド](https://docs.weaviate.io/weaviate/configuration/modules) の説明に従って、環境変数 `ENABLE_MODULES` で有効化してください。

## インストールとセットアップ

**1. 仮想環境の作成**

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

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

**2. 依存パッケージのインストール**

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

本ガイドは `weaviate-client` 4.24.1 と Weaviate 1.40.1 で動作確認済みです。

**3. SambaStack のベース URL と API キーの設定**

ここでは、ベース URL に `/v1` を付けないでください。Weaviate 自身が `/v1/embeddings` と `/v1/chat/completions` を付加するため、末尾がすでに `/v1` になっているベース URL では `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"
```

## モジュールの設定とクエリ

このセクションのステップは、1 つの Python ファイルまたはセッション内で実行してください。各ステップでは、前のステップで定義した変数を使用します。

**1. Weaviate への接続**

Weaviate は、`X-OpenAI-Api-Key` ヘッダーで SambaNova のキーをモジュールに渡します。

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

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

`connect_to_local` は、`localhost` 上のサーバーに接続します。Weaviate Cloud の場合は、`WEAVIATE_URL` にクラスターの URL を、`WEAVIATE_API_KEY` にクラスターの API キーを設定し、同じ `headers` を指定して `connect_to_weaviate_cloud` で接続します。

```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. SambaNova を使用するコレクションの作成**

両方のモジュールに `base_url` を設定し、SambaNova のモデル名を指定します。ベクトルのサイズは Weaviate がモデルから読み取るため、次元数の設定は不要です。

```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",
    ),
)
```

`SambaNovaDemo` コレクションがすでに存在する場合、このコードは先にそれを削除するため、毎回クリーンなコレクションから実行を開始できます。

`text2vec_openai` が Embedding を、`Generative.openai` がチャット補完を担当します。SambaNova を呼び出すのは Weaviate サーバー側であるため、SambaStack インスタンスには Weaviate の実行場所から到達できる必要があります。

**3. ドキュメントの追加**

Weaviate は、挿入された各オブジェクトをその場で埋め込みます。渡すのはテキストだけで、ベクトルを直接扱う必要はありません。

```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. 意味による検索**

```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']}")
```

距離が小さいほど、近い一致です。最も近い一致は SN40L チップに関するパッセージで、コサイン距離は約 0.33 です。次に近いものは約 0.43 です。

**5. SambaNova チャットモデルでの回答生成**

Weaviate は、最も近いオブジェクトを取得し、1 回の呼び出しで生成モジュールに渡します。

```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)
```

モデルは、SambaNova が SN40L チップを製造していると回答します。

**6. コレクションの削除と接続のクローズ**

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

## SambaCloud での Weaviate の利用

SambaCloud は Embedding を提供していないため、テキストはローカルモデルで自分で埋め込み、回答の生成のみ Weaviate の生成モジュールから SambaCloud を呼び出します。FastEmbed をインストールし、`SAMBANOVA_BASE_URL` を `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()
```

## 参考情報

> [card] [Weaviate ドキュメント](https://docs.weaviate.io/weaviate)
>
> コレクション、検索、デプロイを扱う公式ガイドです。

> [card] [Weaviate の OpenAI Embedding](https://docs.weaviate.io/weaviate/model-providers/openai/embeddings)
>
> `text2vec-openai` モジュールとそのパラメータのリファレンスです。

> [card] [Weaviate の OpenAI 生成 AI](https://docs.weaviate.io/weaviate/model-providers/openai/generative)
>
> `generative-openai` モジュールとそのパラメータのリファレンスです。

> [card] [Embedding (埋め込み) 機能の実装](https://docs.sambanova.ai/docs/ja/features/embeddings.md)
>
> SambaStack で SambaNova の Embedding モデルを利用する方法です。

## トラブルシューティング

> [accordion] KeyError: 'SAMBANOVA\_BASE\_URL'
>
> 環境変数が、Python を実行するシェルに設定されていません。エラーには、`SAMBANOVA_BASE_URL` や `SAMBANOVA_API_KEY` など、不足している変数名が表示されます。[インストールとセットアップ](#インストールとセットアップ) のとおり設定し、同じシェルからコードを再実行してください。Weaviate Cloud の場合は、`WEAVIATE_URL` と `WEAVIATE_API_KEY` も設定してください。

> [accordion] failed to parse vectorization response (status 404)
>
> ベース URL の末尾が `/v1` になっています。Weaviate はベース URL に `/v1/embeddings` を付加するため、結果として `/v1/v1/embeddings` を呼び出すことになります。`base_url` には `/v1` を付けない SambaStack のベース URL を設定し、コレクションを作成し直してください。

> [accordion] API Key: no api key found neither in request header: X-Openai-Api-Key
>
> 接続に、モジュールへ渡すキーがありません。`connect_to_local` または `connect_to_weaviate_cloud` に `headers={"X-OpenAI-Api-Key": ...}` を渡し、Python を実行するシェルで `SAMBANOVA_API_KEY` がエクスポートされていることを確認してください。

> [accordion] connection to: OpenAI API failed with status: 401
>
> キーがベース URL と一致していません。お使いの SambaStack インスタンス用に発行されたキーを使用してください。

> [accordion] connection to: OpenAI API failed with status: 404 ... model does not exist
>
> コレクションで指定したモデルをインスタンスがサービングしていないか、キーにアクセス権がありません。インスタンスがサービングしているモデルの一覧を確認してください。
>
> ```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 は Embedding を提供していません。[SambaCloud での Weaviate の利用](#sambacloud-での-weaviate-の利用) をご参照ください。

> [accordion] 422: class name SambaNovaDemo already exists
>
> 上記のコードは、既存の `SambaNovaDemo` コレクションを先に削除します。このチェックを削除した場合は、`client.collections.delete("SambaNovaDemo")` で削除してください。
