README

ChromaDB PHP API 客户端

ChromaDB 是一个开源的矢量数据库，允许您存储和查询矢量嵌入。本软件包提供了 ChromaDB API 的 PHP 客户端。

安装

您可以通过 composer 安装此软件包

composer require helgesverre/chromadb

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="chromadb-config"

这是已发布 config/chromadb.php 文件的内容

return [
    'token' => env('CHROMADB_TOKEN'),
    'host' => env('CHROMADB_HOST', 'localhost'),
    'port' => env('CHROMADB_PORT', '19530'),
];

使用方法

$chromadb = new \HelgeSverre\Chromadb\Chromadb(
    token: 'test-token-chroma-local-dev',
    host: 'https://',
    port: '8000'
);

// Create a new collection with optional metadata
$chromadb->collections()->create(
    name: 'my_collection',
);

// Count the number of collections
$chromadb->collections()->count();

// Retrieve a specific collection by name
$chromadb->collections()->get(
    collectionName: 'my_collection'
);

// Delete a collection by name
$chromadb->collections()->delete(
    collectionName: 'my_collection'
);

// Update a collection's name and/or metadata
$chromadb->collections()->update(
    collectionId: '3ea5a914-e2ab-47cb-b285-8e585c9af4f3',
    newName: 'new_collection_name',
);

// Add items to a collection with optional embeddings, metadata, and documents
$chromadb->items()->add(
    collectionId: '3ea5a914-e2ab-47cb-b285-8e585c9af4f3',
    ids: ['item1', 'item2'],
    embeddings: ['embedding1', 'embedding2'],
    documents: ['doc1', 'doc2']
);

// Update items in a collection with new embeddings, metadata, and documents
$chromadb->items()->update(
    collectionId: '3ea5a914-e2ab-47cb-b285-8e585c9af4f3',
    ids: ['item1', 'item2'],
    embeddings: ['new_embedding1', 'new_embedding2'],
    documents: ['new_doc1', 'new_doc2']
);

// Upsert items in a collection (insert if not exist, update if exist)
$chromadb->items()->upsert(
    collectionId: '3ea5a914-e2ab-47cb-b285-8e585c9af4f3',
    ids: ['item'],
    metadatas: [['title' => 'metadata']],
    documents: ['document']
);

// Retrieve specific items from a collection by their IDs
$chromadb->items()->get(
    collectionId: '3ea5a914-e2ab-47cb-b285-8e585c9af4f3',
    ids: ['item1', 'item2']
);

// Delete specific items from a collection by their IDs
$chromadb->items()->delete(
    collectionId: '3ea5a914-e2ab-47cb-b285-8e585c9af4f3',
    ids: ['item1', 'item2']
);

// Count the number of items in a collection
$chromadb->items()->count(
    collectionId: '3ea5a914-e2ab-47cb-b285-8e585c9af4f3'
);

// Query items in a collection based on embeddings, texts, and other filters
$chromadb->items()->query(
    collectionId: '3ea5a914-e2ab-47cb-b285-8e585c9af4f3',
    queryEmbeddings: [createTestVector(0.8)],
    include: ['documents', 'metadatas', 'distances'],
    nResults: 5
);

示例：使用 ChromaDB 和 OpenAI 嵌入进行语义搜索

此示例演示了如何使用 OpenAI 生成的嵌入在 ChromaDB 中执行语义搜索。

完整代码可在 SemanticSearchTest.php 中找到。

准备您的数据

首先，创建一个您希望索引的数据数组。在此示例中，我们将使用具有标题、摘要和标签的博客文章。

$blogPosts = [
    [
        'title' => 'Exploring Laravel',
        'summary' => 'A deep dive into Laravel frameworks...',
        'tags' => ['PHP', 'Laravel', 'Web Development']
    ],
    [
        'title' => 'Introduction to React',
        'summary' => 'Understanding the basics of React and how it revolutionizes frontend development.',
        'tags' => ['JavaScript', 'React', 'Frontend']
    ],
];

生成嵌入

使用 OpenAI 的嵌入 API 将您的博客文章摘要转换为矢量嵌入。

$summaries = array_column($blogPosts, 'summary');
$embeddingsResponse = OpenAI::client('sk-your-openai-api-key')
    ->embeddings()
    ->create([
        'model' => 'text-embedding-ada-002',
        'input' => $summaries,
    ]);

foreach ($embeddingsResponse->embeddings as $embedding) {
    $blogPosts[$embedding->index]['vector'] = $embedding->embedding;
}

创建 ChromaDB 集合

在 ChromaDB 中创建一个集合以存储您的博客文章嵌入。

$createCollectionResponse = $chromadb->collections()->create(
    name: 'blog_posts',
);

$collectionId = $createCollectionResponse->json('id');

插入到 ChromaDB

将这些嵌入以及其他博客文章数据插入到您的 ChromaDB 集合中。

foreach ($blogPosts as $post) {
    $chromadb->items()->add(
        collectionId: $collectionId,
        ids: [$post['title']],
        embeddings: [$post['embedding']],
        metadatas: [$post]
    );
}

使用 OpenAI 创建搜索矢量

为您的查询生成一个类似于处理博客文章的搜索矢量。

$searchEmbedding = getOpenAIEmbedding('laravel framework');

在 ChromaDB 中使用嵌入进行搜索

使用 ChromaDB 客户端执行具有生成的嵌入的搜索。

$searchResponse = $chromadb->items()->query(
    collectionId: $collectionId,
    queryEmbeddings: [$searchEmbedding],
    nResults: 3,
    include: ['metadatas']
);

// Output the search results
foreach ($searchResponse->json('results') as $result) {
    echo "Title: " . $result['metadatas']['title'] . "\n";
    echo "Summary: " . $result['metadatas']['summary'] . "\n";
    echo "Tags: " . implode(', ', $result['metadatas']['tags']) . "\n\n";
}

在 Docker 中运行 ChromaDB

要快速开始使用 ChromaDB，您可以在 Docker 中运行它

# Download the docker-compose.yml file
wget https://github.com/HelgeSverre/chromadb/blob/main/docker-compose.yml

# Start ChromaDB
docker compose up -d

默认情况下，认证令牌设置为 test-token-chroma-local-dev。

您可以在 docker-compose.yml 文件中通过更改 CHROMA_SERVER_AUTH_CREDENTIALS 环境变量来更改此设置

要停止 ChromaDB，运行 docker compose down，要擦除所有数据，运行 docker compose down -v。

注意

此存储库中的 docker-compose.yml 文件仅作为示例提供，不应在生产中使用。

有关在生产中部署 Chroma 的更多信息，请参阅 ChromaDB 的 部署文档。

测试

cp .env.example .env

docker compose up -d
 
composer test
composer analyse src

许可

MIT 许可证 (MIT)。有关更多信息，请参阅 许可文件。