mcpField
C
chroma-local

chroma-local

github.com/chroma-core数据与数据库24134 次安装27 周前更新
代码仓库

关于 chroma-local

chroma-local 是面向开发者的技能，指导在本地开发、测试或自托管部署中集成 Chroma。内容涵盖客户端、持久化方式、嵌入函数和索引策略的选择。

主要功能

  1. 01选择本地运行方式和客户端
  2. 02持久化与临时数据指导
  3. 03选择嵌入函数
  4. 04集合索引与更新模式
  5. 05验证本地服务

适用场景

  1. 01设置本地 Chroma 服务
  2. 02在临时 Python 测试中嵌入 Chroma
  3. 03为应用添加持久化搜索

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/chroma-core/agent-skills --skill chroma-local

安装后在 Claude Code 中输入/chroma-local确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

cli.md
data-model.md
understanding-a-codebase.md
error-handling/
python.md
typescript.md
local-chroma/
python.md
typescript.md
metadata/
python.md
typescript.md
querying/
python.md
typescript.md
regex/
python.md
typescript.md
updating-deleting/
python.md
typescript.md

详细介绍

说明

编写代码前先确定以下事项。优先从代码库和用户请求中查找答案。仅当选择会实质影响实现时才询问。

  1. 运行时形态

    • 他们是要连接正在运行的本地服务、将 Chroma 嵌入测试中，还是从头搭建本地开发环境？
    • 确定他们需要 chroma run、Docker 或服务命令、HttpClient 或 ChromaClient，还是 Python EphemeralClient。

  2. 持久化

    • 本地数据需要持久保存：选择明确的数据路径。
    • 测试数据无需保留：使用默认值或临时目录。

  3. 嵌入模型

    • 尽可能复用应用现有的嵌入提供方。
    • 否则，TypeScript 默认使用 @chroma-core/default-embed，Python 默认使用标准本地默认设置。
    • 如果用户明确要求在 TypeScript 中使用 OpenAI 嵌入，请安装并使用 @chroma-core/openai。

  4. 索引数据形态

    • 确定要索引的内容、应如何分块，以及过滤和更新需要哪些元数据。

路由

  • 已有本地服务

    • 修改客户端代码前确认主机和端口。
    • 假定集合缺失之前，先验证服务是否可访问。

  • 全新本地开发

    • 添加本地启动方式，例如 chroma run 或代码库现有的 Docker 或服务命令。
    • 默认使用 localhost:8000，除非代码库已使用其他地址。

  • Python 测试或临时本地工作流

    • 无需持久化时，优先使用 EphemeralClient。
    • 明确说明进程退出后数据会丢失。

  • 需要持久化的本地开发

    • 使用稳定的数据路径，并在代码或配置中明确持久化设置。
    • 不要在临时模式和持久化模式之间悄然切换。

  • 搜索集成工作

    • TypeScript 使用 getOrCreateCollection()，Python 使用 get_or_create_collection()。
    • 设计文档 ID 和元数据，确保 upsert 和删除操作简单直接。
    • 同步大型数据集时采用批量写入。

先询问还是继续处理

先询问：

  • 嵌入模型的选择（涉及成本和质量）
  • 是否需要持久化本地数据
  • 如何启动本地服务
  • 多租户数据隔离策略

使用合理默认值继续处理：

  • 使用 getOrCreateCollection()（TypeScript）／get_or_create_collection()（Python）
  • 使用余弦相似度（最常见）
  • 分块大小小于 8KB
  • 在元数据中存储来源 ID，以便更新／删除
  • 使用 localhost:8000 上的本地服务，除非代码库已配置其他地址或正在使用 Python EphemeralClient

验证事项

  • 客户端导入是否正确（ChromaClient、HttpClient 或 Client）
  • 是否已安装嵌入函数包（TypeScript）
  • 假定集合缺失之前，本地服务是否可访问
  • 本地路径和持久化模式是否经过明确选择

实现说明

  • 本地 Chroma 是开发、测试和可自托管部署的合适默认选择。
  • 开源版 Chroma 不包含 Chroma Cloud 专属功能，例如 Schema() 和 Search()。
  • 如果用户要求混合密集和稀疏检索，除非代码库已实现开源版变通方案，否则应将其视为很可能需要 Chroma Cloud。
  • 对于开源版 Chroma，使用单个嵌入函数进行密集检索是常规基线。

最简模式

如果代码库需要，请启动本地 Chroma 服务：

chroma run

默认地址：localhost:8000。

TypeScript 本地客户端：

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

const client = new ChromaClient();

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 本地客户端：

import chromadb

client = chromadb.HttpClient(host="localhost", port=8000)

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,
)

了解更多

仅当需要了解代码库或此技能中未涵盖的 API 或产品详情时，才获取 Chroma 的 llms.txt：https://docs.trychroma.com/llms.txt

可用主题

Typescript
Python

通用

评论

支持 Markdown