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

# Chroma

> Chroma の Python クライアントまたは LangChain を通じて、オープンソースのベクトル DB である Chroma で SambaStack の Embedding モデルとチャットモデルを利用します。

[Chroma](https://www.trychroma.com/) は、Python プロセス内またはサーバーとして動作するオープンソースのベクトル DB です。`OpenAIEmbeddingFunction` が `api_base` を受け付けるため、Chroma はドキュメントとクエリの埋め込みを SambaStack の Embedding (埋め込み) モデルで行えます。その後、SambaNova のチャットモデルで質問に回答します。

> [!WARNING]
>
> Embedding は SambaStack のみで提供されています。`E5-Mistral-7B-Instruct` は SambaCloud では利用できません。[Embedding (埋め込み) 機能の実装](https://docs.sambanova.ai/docs/ja/features/embeddings.md) をご参照ください。
>
> SambaCloud でも Chroma 自体は利用できます。`SAMBANOVA_BASE_URL` を `https://api.sambanova.ai/v1` に設定し、`embedding_function` を指定せずに Chroma 組み込みのローカルモデルで埋め込みを行うようにして、ステップ 3 のインストラクション形式の例はスキップしてください。その後は、ステップ 4 のとおり SambaNova のチャットモデルで回答を生成します。LangChain のセクションには SambaStack が必要です。

## 前提条件

* `E5-Mistral-7B-Instruct` をサービングしている SambaStack インスタンスと、そのインスタンスのベース URL および API キー。[API キーと URL](https://docs.sambanova.ai/docs/ja/get-started/api-keys-urls.md) をご参照ください。
* 同インスタンス上のチャットモデル。本ガイドでは `gpt-oss-120b` を使用します。
* 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` で対応バージョンをインストールしてください。

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

**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 chromadb openai
```

本ガイドは `chromadb` 1.5.9 と `openai` 3.35.1 で動作確認済みです。

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

ベース URL は、末尾が `/v1` である必要があります。

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

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

## Embedding の生成、保存、クエリ

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

**1. SambaNova で埋め込みを行うコレクションの作成**

Chroma の `OpenAIEmbeddingFunction` に `api_base` と `api_key_env_var` を渡します。`api_key_env_var` を指定すると、Chroma はデフォルトの `CHROMA_OPENAI_API_KEY` ではなく SambaNova のキーを読み取ります。`api_type` は設定しないでください。Chroma 自身の例では Azure OpenAI 向けに `azure` を設定していますが、ここでは不要です。

```python theme={}
import os
import chromadb
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

embedding_function = OpenAIEmbeddingFunction(
    api_key_env_var="SAMBANOVA_API_KEY",
    api_base=os.environ["SAMBANOVA_BASE_URL"],
    model_name="E5-Mistral-7B-Instruct",
)

client = chromadb.PersistentClient(path="./chroma-data")
collection = client.get_or_create_collection(
    name="sambanova-demo",
    embedding_function=embedding_function,
    configuration={"hnsw": {"space": "cosine"}},
)
```

`PersistentClient` は、コレクションを `./chroma-data` に保存します。すべてをメモリ内に保持する場合は、代わりに `chromadb.EphemeralClient()` を使用してください。Chroma のデフォルトは L2 距離の二乗であるため、`configuration` 引数でコサイン距離を設定しています。テキストの Embedding では、コサイン距離が一般的な選択です。

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

Embedding 関数は Chroma が呼び出すため、渡すのはテキストだけで、ベクトルを直接扱う必要はありません。

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

**3. コレクションのクエリ**

```python theme={}
question = "Which chip does SambaNova make?"
results = collection.query(query_texts=[question], n_results=2)

for doc_id, distance, text in zip(
    results["ids"][0], results["distances"][0], results["documents"][0]
):
    print(f"{distance:.3f} {doc_id} {text}")
```

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

`E5-Mistral-7B-Instruct` はインストラクションチューニング済み (instruction-tuned) のモデルです。Chroma は `query_texts` をプレーンテキストとして埋め込みますが、この例ではそれでも正しいパッセージが最初にランクされます。クエリをインストラクション形式で整形するには、自分で埋め込みを行い、代わりにベクトルを渡します。

```python theme={}
task = "Given a question, retrieve passages that answer the question"
query_embedding = embedding_function([f"Instruct: {task}\nQuery: {question}"])
results = collection.query(query_embeddings=query_embedding, n_results=2)
```

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

検索で取得したパッセージを、コンテキストとしてチャットモデルに渡します。

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

sn = OpenAI(
    base_url=os.environ["SAMBANOVA_BASE_URL"],
    api_key=os.environ["SAMBANOVA_API_KEY"],
)

context = "\n".join(results["documents"][0])
answer = sn.chat.completions.create(
    model="gpt-oss-120b",
    messages=[
        {"role": "system", "content": f"Answer using only the context below.\n\nContext:\n{context}"},
        {"role": "user", "content": question},
    ],
)
print(answer.choices[0].message.content)
```

`question` は、ステップ 3 の検索で使用したものと同じ質問です。

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

**5. 使い終わったコレクションの削除**

```python theme={}
client.delete_collection("sambanova-demo")
```

これでコレクションが削除されます。保存されたデータも削除するには、`./chroma-data` フォルダを削除してください。

## LangChain での Chroma の利用

`langchain-chroma` パッケージは、同じデータベースをラップします。OpenAI Embedding 連携とあわせてインストールします。

```bash theme={}
pip install langchain-chroma langchain-openai
```

本ガイドは `langchain-chroma` 1.1.0 と `langchain-openai` 1.7.2 で動作確認済みです。

`check_embedding_ctx_length=False` を設定してください。設定しない場合、LangChain はテキストではなくトークン ID を送信し、SambaStack の Embedding エンドポイントはこれを拒否します。

```python theme={}
import os
from langchain_chroma import Chroma
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    model="E5-Mistral-7B-Instruct",
    base_url=os.environ["SAMBANOVA_BASE_URL"],
    api_key=os.environ["SAMBANOVA_API_KEY"],
    check_embedding_ctx_length=False,
)

vector_store = Chroma.from_texts(
    [
        "SambaNova builds the SN40L chip, a reconfigurable dataflow unit for fast AI inference.",
        "Chroma is an open-source vector database for AI applications.",
        "Sourdough bread needs a live starter, flour, water, and salt, and a long slow fermentation.",
        "The capital of Brazil is Brasilia, which was inaugurated in 1960.",
    ],
    embeddings,
    ids=["doc1", "doc2", "doc3", "doc4"],
    collection_name="sambanova-langchain",
    collection_configuration={"hnsw": {"space": "cosine"}},
)

for doc, score in vector_store.similarity_search_with_score("Which chip does SambaNova make?", k=2):
    print(f"{score:.3f} {doc.page_content}")
```

スコアは、直接利用の例と同じコサイン距離です。永続化ストアにするには、`Chroma.from_texts` に `persist_directory="./chroma-data"` を渡してください。

## 参考情報

> [card] [Chroma ドキュメント](https://docs.trychroma.com/)
>
> コレクション、クエリ、サーバーとしての Chroma の実行を扱う公式ガイドです。

> [card] [Chroma の OpenAI Embedding 関数](https://docs.trychroma.com/integrations/embedding-models/openai)
>
> `OpenAIEmbeddingFunction` とそのパラメータのリファレンスです。

> [card] [LangChain の Chroma 連携](https://docs.langchain.com/oss/python/integrations/vectorstores/chroma)
>
> `langchain-chroma` ベクトルストアのリファレンスです。

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

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

> [accordion] The SAMBANOVA\_API\_KEY environment variable is not set
>
> `api_key_env_var` で指定した環境変数が未設定の場合、Chroma は `ValueError: The SAMBANOVA_API_KEY environment variable is not set.` を送出します。Python を実行するシェルで、この変数をエクスポートしてください。`api_key_env_var` を省略した場合、Chroma は代わりに `CHROMA_OPENAI_API_KEY` を探します。

> [accordion] Embedding エンドポイントが 404 page not found を返す
>
> ベース URL に `/v1` がありません。`SAMBANOVA_BASE_URL` には、SambaStack のベース URL の末尾に `/v1` を付けた値を設定してください。

> [accordion] Embedding エンドポイントが 401 invalid\_api\_key を返す
>
> キーがベース URL と一致していません。お使いの SambaStack インスタンス用に発行されたキーを使用してください。

> [accordion] text-embedding-ada-002 に対する 404 model\_not\_found
>
> `model_name` を設定していないため、Chroma がデフォルトモデルの `text-embedding-ada-002` をリクエストしています。`model_name="E5-Mistral-7B-Instruct"` を設定してください。エラーに `E5-Mistral-7B-Instruct` が表示される場合は、お使いの SambaStack インスタンスが同モデルをサービングしていないか、キーにアクセス権がありません。インスタンスがサービングしているモデルの一覧は、`curl -H "Authorization: Bearer $SAMBANOVA_API_KEY" "$SAMBANOVA_BASE_URL/models"` で確認できます。

> [accordion] 400 Invalid type for 'input': expected string, got array
>
> このエラーは LangChain の例で発生します。上記のとおり、`OpenAIEmbeddings` に `check_embedding_ctx_length=False` を渡してください。
