README

ChromaDB PHP 库的 Laravel 方便包装器，用于无缝与 Chroma 矢量数据库交互。

注意：此包是围绕 ChromaDB PHP 库的包装器。它旨在在 Laravel 应用程序中使用。如果您正在寻找独立或无框架的方式在 PHP 中与 Chroma 交互，请查看 ChromaDB PHP 库。

安装

您可以通过 composer 安装此包

composer require codewithkyrian/chromadb-laravel

安装包后，您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Codewithkyrian\ChromaDB\ChromaServiceProvider" --tag="config"

这将发布一个包含以下内容的 chromadb.php 文件到您的配置目录

return [
    /*
     |--------------------------------------------------------------------------
     | ChromaDB Host
     |--------------------------------------------------------------------------
     |
     | Here you may specify your ChromaDB Host. This is the host where your ChromaDB
     | instance is running. This is used to connect to your ChromaDB instance.
     */
    'host' => env('CHROMA_HOST', 'localhost'),

    /*
     |--------------------------------------------------------------------------
     | ChromaDB Port
     |--------------------------------------------------------------------------
     |
     | Here you may specify your ChromaDB Port. This is the port where your ChromaDB
     | instance is running. This is used to connect to your ChromaDB instance.
     */
    'port' => env('CHROMA_PORT', 8000),

    /*
     |--------------------------------------------------------------------------
     | ChromaDB Tenant
     |--------------------------------------------------------------------------
     |
     | This is the tenant that you want to connect to.
     */
    'tenant' => env('CHROMA_TENANT', 'default_tenant'),

    /*
     |--------------------------------------------------------------------------
     | ChromaDB Database
     |--------------------------------------------------------------------------
     |
     | This is the database that you want to connect to.
     */
    'database' => env('CHROMA_DATABASE', 'default_database'),


    /*
     |--------------------------------------------------------------------------
     | ChromaDB Sync
     |--------------------------------------------------------------------------
     |
     | This is the configuration for the ChromaDB Sync feature. This feature
     | allows you to sync data from your local database to your ChromaDB
     | instance.
     */
    'sync' => [

        /*
         |--------------------------------------------------------------------------
         | ChromaDB Sync Enabled
         |--------------------------------------------------------------------------
         |
         | This option controls whether the ChromaDB Sync feature is enabled. If
         | this is set to false, then the ChromaDB Sync feature will not be
         | enabled.
         */
        'enabled' => env('CHROMA_SYNC_ENABLED', true),

        /*
         |--------------------------------------------------------------------------
         | ChromaDB Sync Queue
         |--------------------------------------------------------------------------
         |
         | This option controls which queue the ChromaDB Sync feature will use.
         | This is used to queue the sync jobs. Set to false to disable queueing
         | and run the sync jobs immediately.
         */
        'queue' => env('CHROMA_SYNC_QUEUE', 'default'),

        /*
         |--------------------------------------------------------------------------
         | ChromaDB Sync Connection
         |--------------------------------------------------------------------------
         |
         | This option controls which connection the ChromaDB Sync feature will use.
         | This is used to queue the sync jobs.
         */
        'connection' => env('CHROMA_SYNC_CONNECTION', 'database'),

        /*
         |--------------------------------------------------------------------------
         | ChromaDB Sync Tries
         |--------------------------------------------------------------------------
         |
         | This option controls how many times the Job will be retried if it fails
         | while trying to sync the data to ChromaDB.
         */
        'tries' => env('CHROMA_SYNC_TRIES', 3),

    ],
];

如您所见，所有配置选项都是从环境变量中检索的，因此您可以在不修改配置文件的情况下轻松地在 .env 文件中设置它们。

CHROMA_HOST=http://localhost
CHROMA_PORT=8080
CHROMA_TENANT=default
CHROMA_DATABASE=default
CHROMA_SYNC_ENABLED=true
CHROMA_SYNC_QUEUE=default
CHROMA_SYNC_CONNECTION=database
CHROMA_SYNC_TRIES=3

使用方法

当然，在您可以使用此包之前，需要先运行 ChromaDB 服务器。有关如何运行 ChromaDB 的说明，请参阅 ChromaDB 网站。

use Codewithkyrian\ChromaDB\Facades\ChromaDB;

ChromaDB::version(); // Eg. 0.4.2

$collection = ChromaDB::createCollection('collection_name');

$collection = ChromaDB::getCollection('collection_name');

$collection = ChromaDB::deleteCollection('collection_name');

$collections = ChromaDB::listCollections();

有关更多使用示例，请参阅 ChromaDB PHP 库。

与 Eloquent 模型一起工作

此包附带一个您可以使用它将 Eloquent 模型与 ChromaDB 集合相关联并自动同步到 ChromaDB 的特性。要开始，请将 ChromaModel 接口和 HasChromaCollection 特性添加到您的模型中。

use Codewithkyrian\ChromaDB\Contracts\ChromaModel;
use Codewithkyrian\ChromaDB\Concerns\HasChromaCollection;

class User extends Model implements ChromaModel
{
    use HasChromaCollection;
    
    // ...
}

之后，您需要在模型中实现一些方法。

documentFields() - 此方法应返回一个数组，其中包含您希望用于形成嵌入 ChromaDB 集合的文档的字段。它将此数组中的字段合并为一个字符串，并使用该字符串作为文档。此方法为可选，但如果您不实现它，则必须实现 toChromaDocument() 方法。
```
  public function documentFields(): array
  {
      return [
          'first_name',
          'last_name',
      ];
  }
```
embeddingFunction() - 此方法应返回您想要用于将模型嵌入 ChromaDB 集合的嵌入函数的名称。您可以使用任何内置嵌入函数或通过实现 EmbeddingFunction 接口（包括匿名类）创建自己的嵌入函数。
```
    use Codewithkyrian\ChromaDB\Embeddings\JinaEmbeddingFunction;

    public function embeddingFunction(): string
    {
        return new JinaEmbeddingFunction('jina-api-key');
    }
```
collectionName() - 此方法应返回您希望与您的模型关联的 ChromaDB 集合的名称。默认情况下，它返回模型的表名。
toChromaDocument()（可选）- 如果您不喜欢 documentFields() 方法中合并字段的默认方式，您可以实现此方法以返回将嵌入到 ChromaDB 集合中的文档。
```
  public function toChromaDocument(): string
  {
      return $this->first_name . ' ' . $this->last_name;
  }
```
metadataFields() (可选) - 此方法应返回一个数组，包含您希望用于形成嵌入到 ChromaDB 集合中的元数据字段。它将被保存为 ChromaDB 集合中的 JSON 对象。默认情况下，它只返回 id 字段，因此元数据将是 { "id": 1 }。
```
    public function metadataFields(): array
    {
        return [
            'id',
            'first_name',
            'last_name',
        ];
    }
```

toChromaMetadata() (可选) - 如果您想对将嵌入到 ChromaDB 集合中的元数据有更多控制，您可以实现此方法来返回将嵌入到 ChromaDB 集合中的元数据。请确保返回关联数组。

  public function toChromaMetadata(): array
  {
      return [
          'id' => $this->id,
          'first_name' => $this->first_name,
          'last_name' => $this->last_name,
      ];
  }

实现上述方法后（只需要两个），您的模型现在有一个 getChromaCollection() 方法，您可以使用它来获取与您的模型关联的 ChromaDB 集合。

$collection = User::getChromaCollection();

$collection->name; // users
$collection->count();

同步模型到 ChromaDB

默认情况下，该包将在模型创建、更新或删除时自动将其同步到 ChromaDB，前提是自上次同步以来属性发生了变化。您可以通过设置 chromadb.sync.enabled 配置选项为 false 或将 CHROMA_SYNC_ENABLED 设置为 false 来禁用此功能。

模型同步是排队进行的，因此请确保按照 Laravel 推荐的方式设置队列和工作者。您可以在配置中设置队列、连接和作业尝试次数，或分别使用 CHROMA_SYNC_QUEUE、CHROMA_SYNC_CONNECTION 和 CHROMA_SYNC_TRIES。但是，您可以将 CHROMA_SYNC_QUEUE 设置为 false 以禁用使用队列进行同步。

查询集合

尽管您可以从 getChromaCollection() 方法获取集合后继续查询集合，您也可以使用模型来查询集合。该模型有一个 queryChromaCollection() 命名空间，您可以使用它来查询集合。

$searchTerm = 'Kyrian';

$users = User::queryChromaCollection($searchTerm, 10)
            ->where('first_name', 'John')
            ->get();

queryChromaCollection() 方法的参数与 ChromaDB PHP 库中的 query() 方法的参数相同。此外，此方法按结果中的 distance 字段排序结果。

截断集合

您可以使用模型上的 truncateChromaCollection() 方法来截断与模型关联的集合。

User::truncateChromaCollection();

测试

// Run chroma by running the docker compose file in the repo
docker compose up -d

composer test

贡献者

Kyrian Obikwelu
欢迎其他贡献者。

许可

本项目采用 MIT 许可证。有关更多信息，请参阅 LICENSE 文件。

codewithkyrian / chromadb-laravel

维护者

详细信息