管理集合

Chroma 允许您使用 collection 原语来管理嵌入集合。集合是 Chroma 中存储和查询的基本单位。

创建集合

Chroma 集合是带名称创建的。集合名称会用于 URL 中，因此对其有一些限制：

名称长度必须在 3 到 512 个字符之间。
名称必须以小写字母或数字开头和结尾，中间可以包含点、连字符和下划线。
名称不得包含两个连续的点。
名称不得是有效的 IP 地址。

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

请注意，集合名称在 Chroma 数据库内必须是唯一的。如果您尝试创建与现有集合同名的集合，将会看到异常。

嵌入函数

当您向集合添加文档时，Chroma 将使用集合的 嵌入函数 (embedding function) 为您进行嵌入。Chroma 默认使用 sentence transformer 嵌入函数。 Chroma 还提供各种嵌入函数，您可以在创建集合时提供。例如，您可以使用 OpenAIEmbeddingFunction 创建集合：

Python
TypeScript
Rust

安装 openai 包

pip install openai

使用 OpenAIEmbeddingFunction 创建集合

import os
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

collection = client.create_collection(
    name="my_collection",
    embedding_function=OpenAIEmbeddingFunction(
        api_key=os.getenv("OPENAI_API_KEY"),
        model_name="text-embedding-3-small"
    )
)

除了让 Chroma 嵌入文档外，您还可以在向集合添加数据时直接提供嵌入。在这种情况下，您的集合将不会设置嵌入函数，您将负责在添加数据和查询时直接提供嵌入。

collection = client.create_collection(
    name="my_collection",
    embedding_function=None
)

安装 @chroma-core/openai 包以访问 OpenAIEmbeddingFunction

npm install @chroma-core/openai

使用 OpenAIEmbeddingFunction 创建集合

import { OpenAIEmbeddingFunction } from "@chroma-core/openai";

const collection = await client.createCollection({
  name: "my_collection",
  embeddingFunction: new OpenAIEmbeddingFunction({
    apiKey: process.env.OPENAI_API_KEY,
    modelName: "text-embedding-3-small",
  }),
});

const collection = await client.createCollection({
  name: "my_collection",
  embeddingFunction: null,
});

Rust 客户端在使用 add、get、search 等函数时，要求直接提供嵌入。请使用您的供应商 SDK 生成嵌入，然后将其传递给 Chroma。

collection.add(
    vec!["id1".to_string(), "id2".to_string(), "id3".to_string()],
    vec![
        vec![1.1, 2.3, 3.2],
        vec![4.5, 6.9, 4.4],
        vec![1.1, 2.3, 3.2],
    ],
    Some(vec![
        Some("lorem ipsum...".to_string()),
        Some("doc2".to_string()),
        Some("doc3".to_string()),
    ]),
    None,
    None,
).await?;

集合元数据

在创建集合时，您可以传递可选的 metadata 参数，向集合添加元数据键值对映射。这对于添加关于集合的常规信息非常有用，例如创建时间、集合中存储的数据描述等。

from datetime import datetime

collection = client.create_collection(
    name="my_collection",
    embedding_function=emb_fn,
    metadata={
        "description": "my first Chroma collection",
        "created": str(datetime.now())
    }
)

获取集合

Python
TypeScript
Rust

集合创建后，有几种方法可以获取它。get_collection 函数将根据名称从 Chroma 获取集合。它返回一个包含 name、metadata、configuration 和 embedding_function 的 Collection 对象。

collection = client.get_collection(name="my-collection")

get_or_create_collection 函数的行为类似，但如果集合不存在则会创建它。您可以向其传递 create_collection 预期的相同参数，如果集合已存在，客户端将忽略这些参数。

collection = client.get_or_create_collection(
    name="my-collection",
    metadata={"description": "..."}
)

list_collections 函数返回您 Chroma 数据库中的所有集合。集合将按创建时间从旧到新排序。

collections = client.list_collections()

默认情况下，list_collections 最多返回 100 个集合。如果您有超过 100 个集合，或者只需要获取集合的一个子集，可以使用 limit 和 offset 参数。

first_collections_batch = client.list_collections(limit=100) # get the first 100 collections
second_collections_batch = client.list_collections(limit=100, offset=100) # get the next 100 collections
collections_subset = client.list_collections(limit=20, offset=50) # get 20 collections starting from the 50th

当前版本的 Chroma 会在服务器上存储您用于创建集合的嵌入函数，以便客户端在后续的“获取”操作中为您解析它。如果您运行的是较旧版本的 Chroma 客户端或服务器（早于 1.1.13），则在使用 get_collection 时需要提供与创建集合时相同的嵌入函数。

collection = client.get_collection(
    name='my-collection',
    embedding_function=ef
)

集合创建后，有几种方法可以获取它。getCollection 函数将根据名称从 Chroma 获取集合。它返回一个包含 name、metadata、configuration 和 embeddingFunction 的集合对象。如果您在 createCollection 时没有提供嵌入函数，可以将其提供给 getCollection。

const collection = await client.getCollection({ name: "my-collection " });

getOrCreate 函数的行为类似，但如果集合不存在则会创建它。您可以向其传递 createCollection 预期的相同参数，如果集合已存在，客户端将忽略这些参数。

const collection = await client.getOrCreateCollection({
  name: "my-collection",
  metadata: { description: "..." },
});

如果您需要一次获取多个集合，可以使用 getCollections()。

const [col1, col2] = client.getCollections(["col1", "col2"]);

listCollections 函数返回您 Chroma 数据库中的所有集合。集合将按创建时间从旧到新排序。

const collections = await client.listCollections();

默认情况下，listCollections 最多返回 100 个集合。如果您有超过 100 个集合，或者只需要获取集合的一个子集，可以使用 limit 和 offset 参数。

const firstCollectionsBatch = await client.listCollections({ limit: 100 }); // get the first 100 collections
const secondCollectionsBatch = await client.listCollections({
  limit: 100,
  offset: 100,
}); // get the next 100 collections
const collectionsSubset = await client.listCollections({
  limit: 20,
  offset: 50,
}); // get 20 collections starting from the 50th

当前版本的 Chroma 会在服务器上存储您用于创建集合的嵌入函数，以便客户端在后续的“获取”操作中为您解析它。如果您运行的是较旧版本的 Chroma JS/TS 客户端（早于 3.04）或服务器（早于 1.1.13），则在使用 getCollection 和 getCollections 时需要提供与创建集合时相同的嵌入函数。

const collection = await client.getCollection({
  name: "my-collection",
  embeddingFunction: ef,
});

const [col1, col2] = client.getCollections([
  { name: "col1", embeddingFunction: openaiEF },
  { name: "col2", embeddingFunction: defaultEF },
]);

使用客户端获取集合或通过分页列出集合。

let collection = client.get_collection("my-collection").await?;

let collection = client
    .get_or_create_collection("my-collection", None, None)
    .await?;

let collections = client.list_collections(100, Some(0)).await?;

修改集合

集合创建后，您可以使用 modify 方法修改其名称、元数据以及索引配置的元素。

collection.modify(
   name="new-name",
   metadata={"description": "new description"}
)

删除集合

您可以按名称删除集合。此操作将删除集合、其所有嵌入以及关联的文档和记录元数据。

删除集合具有破坏性且不可逆。

client.delete_collection(name="my-collection")

便捷方法

集合还提供了一些有用的便捷方法：

count - 返回集合中的记录数量。
peek - 返回集合中的前 10 条记录。

collection.count()
collection.peek()

概述

运行 Chroma

集合 (Collections)

查询集合

向量嵌入 (Embeddings)

命令行界面 (CLI)

创建集合

嵌入函数

集合元数据

获取集合

修改集合

删除集合

便捷方法

概述

运行 Chroma

集合 (Collections)

查询集合

向量嵌入 (Embeddings)

命令行界面 (CLI)

​创建集合

​嵌入函数

​集合元数据

​获取集合

​修改集合

​删除集合

​便捷方法

创建集合

嵌入函数

集合元数据

获取集合

修改集合

删除集合

便捷方法