chroma

手順

コードを書く前に、次の情報を確認してください。

1. デプロイ先：ローカル Chroma と Chroma Cloud のどちらですか？

   • Cloud の場合：API キー、テナント、データベースの設定が必要です
   • Local の場合：永続化ストレージが必要か、一時ストレージでよいかを確認してください

2. 検索タイプ（Cloud のみ）：Dense のみですか、それともハイブリッド検索ですか？

   • Dense のみ：設定が簡単で、ほとんどのセマンティック検索に適しています
   • Hybrid（dense + sparse）：キーワードが多いクエリに適しています。SPLADE を使用してください

3. 埋め込みモデル：どのプロバイダー／モデルを使用しますか？

   • デフォルト：@chroma-core/default-embed（TypeScript）、または組み込み（Python）
   • OpenAI：text-embedding-3-large が最も人気があり、@chroma-core/openai が必要です
   • 希望するモデルや既存のプロバイダーがあるか、ユーザーに確認してください

4. データ構造：何をインデックス化しますか？

   • チャンク分割の方針を決めるために必要です
   • フィルタリング用のメタデータスキーマを設計するために必要です

判断ワークフロー

• ユーザーが検索の追加を希望している
• ローカル Chroma と Chroma Cloud のどちらを使うか尋ねる
  • Local Chroma
    • Dense 埋め込みモデルで collection.query() を使用する
  • Chroma Cloud
    • ハイブリッド検索が必要か尋ねる
      • はい
        • SPLADE のスパースインデックスを使い、Schema() + Search() API を使用する
      • いいえ
        • Dense 埋め込みモデルで collection.query() を使用する
• 使用する埋め込みモデルを尋ねる
• メタデータスキーマを設計する
• データ同期の方針を実装する

質問する場合と、そのまま進める場合

まず確認する項目：

• 埋め込みモデルの選択（コストと品質に影響します）
• Cloud とローカルのどちらにデプロイするか
• ハイブリッド検索と Dense のみの検索のどちらにするか
• マルチテナントのデータ分離方針

妥当なデフォルト値で進める項目：

• getOrCreateCollection() / get_or_create_collection() を使用する
• コサイン類似度を使用する（最も一般的です）
• チャンクサイズは 8KB 未満にする
• 更新／削除に備えて、ソース ID をメタデータに保存する

検証する項目

• Cloud へのデプロイに必要な環境変数が設定されている
• クライアントのインポートが正しい（CloudClient と Client のどちらか）
• 埋め込み関数のパッケージがインストールされている（TypeScript）
• Schema API と Search API は Cloud でのみ使用されている
• 重要： get_or_create_collection() には embedding_function または schema のどちらか一方を渡せますが、両方は渡せません。複数のインデックス（ハイブリッド検索）やスパース埋め込みが必要な場合は Schema を使用し、シンプルな Dense のみの検索には embedding_function を使用してください。

クイックスタート

Chroma Cloud のセットアップ（CLI）

Chroma Cloud を始めるには、CLI を使ってログインし、データベースを作成して、認証情報を .env ファイルに書き込みます。

chroma login
chroma db create <my_database_name>
chroma db connect <my_database_name> --env-file

これにより、現在のディレクトリに CHROMA_API_KEY、CHROMA_TENANT、CHROMA_DATABASE を含む .env ファイルが書き込まれます。以下のコード例では、これらの環境変数を読み込みます。

TypeScript（Chroma Cloud）：

import { CloudClient } from 'chromadb';
import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';

const client = new CloudClient({
  apiKey: process.env.CHROMA_API_KEY,
  tenant: process.env.CHROMA_TENANT,
  database: process.env.CHROMA_DATABASE,
});

const embeddingFunction = new DefaultEmbeddingFunction();
const collection = await client.getOrCreateCollection({
  name: 'my_collection',
  embeddingFunction,
});

// Add documents
await collection.add({
  ids: ['doc1', 'doc2'],
  documents: ['First document text', 'Second document text'],
});

// Query
const results = await collection.query({
  queryTexts: ['search query'],
  nResults: 5,
});

Python（Chroma Cloud）：

import os
import chromadb

client = chromadb.CloudClient(
    api_key=os.environ["CHROMA_API_KEY"],
    tenant=os.environ["CHROMA_TENANT"],
    database=os.environ["CHROMA_DATABASE"],
)

collection = client.get_or_create_collection(name="my_collection")

# Add documents
collection.add(
    ids=["doc1", "doc2"],
    documents=["First document text", "Second document text"],
)

# Query
results = collection.query(
    query_texts=["search query"],
    n_results=5,
)

Chroma を理解する

Chroma はデータベースです。 Chroma データベースにはコレクションが含まれます。 コレクションにはドキュメントが含まれます。

リレーショナルデータベースのテーブルとは異なり、コレクションはアプリケーションレベルで作成および削除されます。各 Chroma データベースには数百万のコレクションを作成できます。ユーザー、チーム、または組織ごとにコレクションを作成することもできます。テーブルを何らかのキーで分割するのではなく、Chroma ではコレクションがパーティションになります。

コレクションには行ではなくドキュメントが含まれます。ドキュメントは検索対象のテキストデータです。データを作成または更新すると、クライアントがそのデータの埋め込みを作成します。これは、クライアントに指定された埋め込み関数に基づいて、クライアント側で行われます。埋め込みを作成するために、クライアントは設定を使用して、埋め込み関数を介して指定された埋め込みモデルプロバイダーを呼び出します。これはプロセス内で行われる場合もありますが、大半は HTTP 経由でサードパーティのサービス上で行われます。

ドキュメントのメタデータを使って、データをさらに分割またはフィルタリングする方法もあります。各ドキュメントには、キーと値のオブジェクト形式のメタデータがあります。キーは文字列で、値には文字列、整数、またはブール値を指定できます。メタデータにはさまざまな演算子を使用できます。

クエリ時には、クエリテキストがコレクションに定義された埋め込み関数を使って埋め込みに変換され、その後、ほかのクエリパラメーターとともに Chroma に送信されます。次に Chroma は、メタデータフィルターなどのクエリパラメーターを使って結果候補を絞り込み、クエリ対象のコレクション内のベクトルインデックスとクエリベクトルの間の距離アルゴリズムを使って、最も近い近傍を検索します。

Chroma クライアントの get_or_create_collection()（TypeScript では getOrCreateCollection()）を使うと、定型コードに煩わされることなく、簡単にコレクションを操作できます。

ローカルとクラウド

Chroma はプロセスとしてローカルで実行することも、Chroma Cloud を使ってクラウドで利用することもできます。

ローカルでできることはすべてクラウドでもできますが、クラウドでできることのすべてをローカルでできるわけではありません。

開発者の操作性に最も大きく影響する違いは Schema() API と Search() API です。これらは Chroma Cloud でのみ利用できます。

それ以外に変更が必要なのは、Chroma パッケージからインポートするクライアントだけで、インターフェースは同じです。

クラウドを使用する場合は、Schema() API と Search() API の使用をおすすめします。

また、ユーザーがクラウドを使いたい場合は、どの種類の検索を使いたいかを確認してください。密な埋め込みのみを使うのか、ハイブリッド検索を使うのかを尋ねます。ハイブリッド検索の場合は、スパース埋め込みの方式として SPLADE を使うことをおすすめします。

埋め込み

埋め込み関数を使う際は、デフォルトの埋め込み関数を利用できますが、最適な選択肢ではないことがよくあります。推奨される選択肢は Chroma Cloud Qwen です。TypeScript の場合は npm install @chroma-core/chroma-cloud-qwen を実行します。Python ではパッケージに含まれていますが、pip install httpx が必要です。

TypeScript では埋め込み関数ごとにパッケージをインストールする必要があります。ユーザーの発言に基づいて、適切なものをインストールしてください。

Chroma は SPLADE と Qwen（TypeScript では @chroma-core/chroma-cloud-qwen 経由）のサーバー側埋め込みに対応しています。それ以外の埋め込み関数は外部で処理されることに注意してください。

詳細を見る

このスキルで扱われている内容以上に Chroma について詳しい情報が必要な場合は、包括的なドキュメントを参照するために Chroma の llms.txt を取得してください：https://docs.trychroma.com/llms.txt

利用可能なトピック

Typescript

• Chroma Regex Filtering - Chroma クエリで正規表現フィルターを使用する方法を学びます
• Query and Get - Chroma コレクションのデータをクエリして取得します
• Schema - Schema() は、複数のインデックスを持つコレクションを構成します
• Metadata Arrays - メタデータフィールドに文字列、数値、ブール値の配列を保存してクエリします
• Updating and Deleting - 既存のドキュメントを更新し、コレクションからデータを削除します
• Error Handling - Chroma の使用時に発生するエラーや障害を処理します
• Local Chroma - ローカルの Chroma を実行して使用する方法
• Collection Forking - Chroma Cloud のコピーオンライトによるフォークを使って、コレクションをすぐに複製します
• Search() API - コレクションに対する密ベクトル検索と疎ベクトル検索、およびハイブリッド検索を実行できる、表現力豊かで柔軟な API です

Python

• Chroma Regex Filtering - Chroma クエリで正規表現フィルターを使用する方法を学びます
• Query and Get - Chroma コレクションのデータをクエリして取得します
• Schema - Schema() は、複数のインデックスを持つコレクションを構成します
• Metadata Arrays - メタデータフィールドに文字列、数値、ブール値の配列を保存してクエリします
• Updating and Deleting - 既存のドキュメントを更新し、コレクションからデータを削除します
• Error Handling - Chroma の使用時に発生するエラーや障害を処理します
• Local Chroma - ローカルの Chroma を実行して使用する方法
• Collection Forking - Chroma Cloud のコピーオンライトによるフォークを使って、コレクションをすぐに複製します
• Search() API - コレクションに対する密ベクトル検索と疎ベクトル検索、およびハイブリッド検索を実行できる、表現力豊かで柔軟な API です

一般

• Chroma CLI - クラウドデータベース管理のための Chroma CLI の使い始め方
• Data Model - Chroma がデータを保存する方法の概要
• Integrating Chroma into an existing system - 既存のアプリケーションに Chroma 検索を追加するためのガイダンス