{
"canonical_name": "chroma-core/chroma",
"compilation_id": "pack_ead543eecc2c4048822a5b5eb9487e54",
"created_at": "2026-05-11T10:23:03.950490+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install chromadb` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install chromadb",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_757bd053778043b19e02ed8040e2b20e"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_d0aaea7fac4f215bb66dc3d614a3e6ad",
"canonical_name": "chroma-core/chroma",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/chroma-core/chroma",
"slug": "chroma",
"source_packet_id": "phit_66c9da2f5fa34d29a26558c9dc864360",
"source_validation_id": "dval_ce6db9c989fb420eb0e8d2f3c80e9153"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 2242,
"github_stars": 27933,
"one_liner_en": "Search infrastructure for AI",
"one_liner_zh": "Search infrastructure for AI",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "chroma",
"title_zh": "chroma 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Retrieval Augmentation",
"label_zh": "检索增强",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-retrieval-augmentation",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_66c9da2f5fa34d29a26558c9dc864360",
"page_model": {
"artifacts": {
"artifact_slug": "chroma",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install chromadb",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/chroma-core/chroma#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"检索增强",
"断点恢复流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Search infrastructure for AI"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:546206616 | https://github.com/chroma-core/chroma | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 185,
"forks": 2242,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 27933,
"open_issues": 619,
"pushed_at": null
},
"source_url": "https://github.com/chroma-core/chroma",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Search infrastructure for AI",
"title": "chroma 能力包",
"trial_prompt": "# chroma - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 chroma 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Search infrastructure for AI 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：Chroma项目概述。围绕“Chroma项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-data-flow：数据流与处理流程。围绕“数据流与处理流程”模拟一次用户任务，不展示安装或运行结果。\n5. page-vector-index：向量索引系统。围绕“向量索引系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“Chroma项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-data-flow\n输入：用户提供的“数据流与处理流程”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-vector-index\n输入：用户提供的“向量索引系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“Chroma项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-data-flow：Step 4 必须围绕“数据流与处理流程”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-vector-index：Step 5 必须围绕“向量索引系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/chroma-core/chroma\n- https://github.com/chroma-core/chroma#readme\n- README.md\n- chromadb/__init__.py\n- Cargo.toml\n- clients/python/pyproject.toml\n- clients/js/package.json\n- Dockerfile\n- docker-compose.yml\n- rust/frontend/src/lib.rs\n- rust/worker/src/lib.rs\n- go/pkg/sysdb/coordinator/coordinator.go\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 chroma 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [Bug]: metadata filter does not work over 20 millions chunk.（https://github.com/chroma-core/chroma/issues/4089）；github/github_issue: [Bug]: PersistentClient second-opener hangs ~16 minutes on shared persis（https://github.com/chroma-core/chroma/issues/7040）；github/github_issue: [Security] Unsafe pickle.load() in PersistentLocalHnswSegment enables ar（https://github.com/chroma-core/chroma/issues/6926）；github/github_issue: query(where=...) raises 'Error finding id' after batched adds until WAL （https://github.com/chroma-core/chroma/issues/7032）；github/github_release: 1.5.9（https://github.com/chroma-core/chroma/releases/tag/1.5.9）；github/github_release: foundation-cli-v0.1.0-alpha.3（https://github.com/chroma-core/chroma/releases/tag/foundation-cli-v0.1.0-alpha.3）；github/github_release: 1.5.8（https://github.com/chroma-core/chroma/releases/tag/1.5.8）；github/github_release: 1.5.7（https://github.com/chroma-core/chroma/releases/tag/1.5.7）；github/github_release: 1.5.6（https://github.com/chroma-core/chroma/releases/tag/1.5.6）；github/github_release: 1.5.5（https://github.com/chroma-core/chroma/releases/tag/1.5.5）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: metadata filter does not work over 20 millions chunk.",
"url": "https://github.com/chroma-core/chroma/issues/4089"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: PersistentClient second-opener hangs ~16 minutes on shared persis",
"url": "https://github.com/chroma-core/chroma/issues/7040"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Security] Unsafe pickle.load() in PersistentLocalHnswSegment enables ar",
"url": "https://github.com/chroma-core/chroma/issues/6926"
},
{
"kind": "github_issue",
"source": "github",
"title": "query(where=...) raises 'Error finding id' after batched adds until WAL ",
"url": "https://github.com/chroma-core/chroma/issues/7032"
},
{
"kind": "github_release",
"source": "github",
"title": "1.5.9",
"url": "https://github.com/chroma-core/chroma/releases/tag/1.5.9"
},
{
"kind": "github_release",
"source": "github",
"title": "foundation-cli-v0.1.0-alpha.3",
"url": "https://github.com/chroma-core/chroma/releases/tag/foundation-cli-v0.1.0-alpha.3"
},
{
"kind": "github_release",
"source": "github",
"title": "1.5.8",
"url": "https://github.com/chroma-core/chroma/releases/tag/1.5.8"
},
{
"kind": "github_release",
"source": "github",
"title": "1.5.7",
"url": "https://github.com/chroma-core/chroma/releases/tag/1.5.7"
},
{
"kind": "github_release",
"source": "github",
"title": "1.5.6",
"url": "https://github.com/chroma-core/chroma/releases/tag/1.5.6"
},
{
"kind": "github_release",
"source": "github",
"title": "1.5.5",
"url": "https://github.com/chroma-core/chroma/releases/tag/1.5.5"
}
],
"status": "已收录 10 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Search infrastructure for AI",
"effort": "安装已验证",
"forks": 2237,
"icon": "code",
"name": "chroma 能力包",
"risk": "可发布",
"slug": "chroma",
"stars": 27894,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"检索增强",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# Wiki Documentation for https://github.com/chroma-core/chroma\n\nGenerated on: 2026-05-10 14:46:12 UTC\n\n## Table of Contents\n\n- [Chroma项目概述](#page-overview)\n- [安装与配置](#page-installation)\n- [系统架构](#page-architecture)\n- [数据流与处理流程](#page-data-flow)\n- [向量索引系统](#page-vector-index)\n- [查询执行引擎](#page-query-execution)\n- [Python客户端](#page-python-client)\n- [JavaScript/TypeScript客户端](#page-javascript-client)\n- [嵌入函数集成](#page-embedding-functions)\n- [存储系统](#page-storage)\n\n\n\n## Chroma项目概述\n\n### Related Pages\n\nRelated topics: [系统架构](#page-architecture), [安装与配置](#page-installation)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n- [rust/types/src/collection_schema.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n- [rust/types/src/metadata.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n- [rust/blockstore/src/arrow/root.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n- [rust/worker/src/execution/operators/execute_task.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/execute_task.rs)\n- [rust/worker/src/execution/operators/materialize_logs.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/materialize_logs.rs)\n- [clients/new-js/packages/chromadb/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/README.md)\n- [examples/xai/README.md](https://github.com/chroma-core/chroma/blob/main/examples/xai/README.md)\n- [schemas/embedding_functions/README.md](https://github.com/chroma-core/chroma/blob/main/schemas/embedding_functions/README.md)\n- [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)\n \n\n# Chroma项目概述\n\n## 项目简介\n\nChroma是一个开源的AI数据基础设施项目，专为向量搜索和嵌入式AI应用设计。它提供了完整的向量数据库功能，支持文档存储、元数据过滤、相似性搜索等核心能力。Chroma的核心目标是简化AI应用的开发流程，让开发者能够快速构建基于向量检索的应用程序。\n\n该项目采用Apache 2.0开源许可证，支持Python和JavaScript/TypeScript双语言客户端，同时提供客户端-服务器模式部署选项。Chroma Cloud是其托管服务，提供serverless向量搜索、混合搜索和全文搜索能力。 Sources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n\n## 系统架构\n\n### 整体架构设计\n\nChroma采用混合架构设计，核心存储层使用Rust语言实现，以确保高性能和数据安全。系统支持多种部署模式，包括本地嵌入式部署和客户端-服务器模式。\n\n```mermaid\ngraph TD\n A[Python Client / JS Client] --> B[Chroma Server]\n A --> C[Embedded Mode]\n B --> D[Rust Worker]\n C --> D\n D --> E[Blockstore]\n D --> F[Record Segment]\n E --> G[Arrow Format Storage]\n F --> H[Log Materialization]\n G --> I[Persistent Storage]\n H --> I\n```\n\n### Rust核心组件\n\nChroma的Rust后端包含多个核心模块，这些模块共同协作完成向量数据的存储和检索工作。\n\n| 组件名称 | 路径位置 | 功能描述 |\n|---------|---------|---------|\n| blockstore | rust/blockstore/ | 块存储管理，使用Apache Arrow格式 |\n| types | rust/types/ | 类型定义和数据模型 |\n| worker | rust/worker/src/execution/ | 任务执行和日志物化处理 |\n| record_segment | - | 记录段读写管理 |\n\nSources: [rust/blockstore/src/arrow/root.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs), [rust/types/src/collection_schema.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n## 数据模型\n\n### Collection Schema\n\nChroma使用Schema来定义Collection的结构和索引配置。每个Schema可以包含多个字段定义和索引配置。\n\n```rust\nSchema::default()\n .create_index(None, VectorIndexConfig {\n space: Some(Space::Cosine),\n embedding_function: None,\n source_key: None,\n hnsw: None,\n spann: None,\n }.into())?\n .create_index(Some(\"category\"), StringInvertedIndexConfig {}.into())?\n```\n\nSources: [rust/types/src/collection_schema.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n### 元数据系统\n\nChroma支持丰富的元数据过滤功能，包括多种比较操作符和表达式组合。\n\n```mermaid\ngraph LR\n A[MetadataComparison] --> B[Primitive Comparisons]\n A --> C[Set Comparisons]\n B --> D[= / != / > / >= / < / <=]\n C --> E[$in / $nin]\n \n F[DocumentOperator] --> G[Contains]\n F --> H[NotContains]\n F --> I[Regex]\n F --> J[NotRegex]\n```\n\n支持的元数据比较操作符包括：`=`, `!=`, `>`, `>=`, `<`, `<=` 以及集合操作符 `$in` 和 `$nin`。文档操作符支持 `Contains`、`NotContains`、`Regex` 和 `NotRegex`。 Sources: [rust/types/src/metadata.rs:1-40](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n\n### 索引类型\n\n| 索引类型 | 说明 | 适用范围 |\n|---------|------|---------|\n| VectorIndex | 向量索引，支持HNSW和Spann | 全局向量字段 |\n| StringInvertedIndex | 字符串倒排索引 | 字符串类型字段 |\n| Spann | Spann向量索引 | 向量字段可选 |\n\nSources: [rust/types/src/collection_schema.rs:1-60](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n## 客户端SDK\n\n### Python客户端\n\nPython客户端是最成熟的客户端实现，支持完整的Chroma功能集。\n\n```python\nimport chromadb\n\n# 创建客户端\nchroma = chromadb.Client()\n\n# 创建Collection\ncollection = chroma.create_collection(\n name=\"my-collection\",\n metadata={\"description\": \"My first collection\"}\n)\n\n# 添加文档\ncollection.add(\n documents=[\"Document 1\", \"Document 2\"],\n metadatas=[{\"source\": \"doc1\"}, {\"source\": \"doc2\"}],\n ids=[\"id1\", \"id2\"]\n)\n\n# 查询\nresults = collection.query(\n query_texts=[\"This is a query document\"],\n n_results=2,\n where={\"metadata_field\": \"is_equal_to_this\"}\n)\n```\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md), [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)\n\n### JavaScript/TypeScript客户端\n\n新的JavaScript客户端采用模块化设计，分为多个独立包。\n\n```typescript\nimport { ChromaClient } from \"chromadb\";\n\nconst chroma = new ChromaClient();\nconst collection = await chroma.createCollection({ name: \"test-from-js\" });\n\nfor (let i = 0; i < 20; i++) {\n await collection.add({\n ids: [\"test-id-\" + i.toString()],\n embeddings: [[1, 2, 3, 4, 5]],\n documents: [\"test\"],\n });\n}\n```\n\nSources: [clients/new-js/packages/chromadb/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/README.md)\n\n## 嵌入函数系统\n\n### 架构设计\n\nChroma的嵌入函数系统采用插件化架构，支持多种嵌入服务提供商。每个嵌入函数都有对应的JSON Schema进行配置验证。\n\n```mermaid\ngraph TD\n A[Embedding Function] --> B[Schema Validation]\n B --> C[Config Validation]\n C --> D[API Client]\n D --> E[Embedding Service]\n \n F[OpenAI Schema] --> B\n G[Jina Schema] --> B\n H[TogetherAI Schema] --> B\n I[Qwen Schema] --> B\n```\n\nSources: [schemas/embedding_functions/README.md](https://github.com/chroma-core/chroma/blob/main/schemas/embedding_functions/README.md)\n\n### 支持的嵌入提供商\n\n| 提供商 | NPM包名 | 支持模型 |\n|-------|---------|---------|\n| OpenAI | 内置 | text-embedding-ada-002 等 |\n| Jina | @chroma-core/jina | jina-embeddings-v2-base-en |\n| Together AI | @chroma-core/together-ai | togethercomputer/m2-bert-80M-8k-retrieval |\n| Qwen | @chroma-core/chroma-cloud-qwen | Qwen3-Embedding-0.6B |\n| xAI | 示例 | xAI SDK集成 |\n\nSources: [clients/new-js/packages/ai-embeddings/jina/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/jina/README.md), [clients/new-js/packages/ai-embeddings/together-ai/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/together-ai/README.md), [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md)\n\n### 配置验证\n\n每个嵌入函数都使用JSON Schema Draft-07规范进行配置验证，确保跨语言兼容性。\n\n```python\nfrom chromadb.utils.embedding_functions.schemas import validate_config\n\nconfig = {\n \"api_key_env_var\": \"CHROMA_OPENAI_API_KEY\",\n \"model_name\": \"text-embedding-ada-002\"\n}\nvalidate_config(config, \"openai\")\n```\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)\n\n## 执行流程\n\n### 日志物化流程\n\nChroma使用日志物化（Log Materialization）来处理数据变更，确保数据的一致性和持久性。\n\n```mermaid\ngraph LR\n A[LogRecord] --> B[MaterializeLogInput]\n B --> C[MaterializeLogOperator]\n C --> D[PartitionedMaterializeLogsResult]\n D --> E[Persistent Storage]\n \n F[RecordSegmentReader] -.-> C\n G[Offset IDs] -.-> C\n H[Plan Options] -.-> C\n```\n\nSources: [rust/worker/src/execution/operators/materialize_logs.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/materialize_logs.rs)\n\n### 任务执行流程\n\nAttached Function执行涉及记录段读取、日志偏移量处理和分片管理。\n\n```mermaid\ngraph TD\n A[ExecuteAttachedFunctionInput] --> B[Record Segment Reader]\n B --> C{Is Rebuild / Backfill?}\n C -->|Yes| D[Output Record Segment Reader]\n C -->|No| E[Standard Processing]\n D --> F[Process Materialized Logs]\n E --> F\n F --> G[Log Offset Handling]\n G --> H[Segment Shard Processing]\n H --> I[ExecuteAttachedFunctionOutput]\n```\n\nSources: [rust/worker/src/execution/operators/execute_task.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/execute_task.rs)\n\n## 部署方式\n\n### 本地部署\n\n使用pip安装Python客户端即可开始本地开发：\n\n```bash\npip install chromadb\n```\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n\n### 客户端-服务器模式\n\n```bash\nchroma run --path /chroma_db_path\n```\n\n### 云端部署\n\nChroma Cloud提供托管服务，支持serverless向量搜索、混合搜索和全文搜索。\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n\n### Terraform部署示例\n\n支持使用Terraform在DigitalOcean上自动化部署Chroma实例：\n\n```bash\nexport TF_VAR_chroma_release=\"0.4.12\"\nexport TF_VAR_region=\"ams2\"\nexport TF_VAR_public_access=\"true\"\nexport TF_VAR_enable_auth=\"true\"\nexport TF_VAR_auth_type=\"token\"\nterraform apply -auto-approve\n```\n\nSources: [examples/deployments/do-terraform/README.md](https://github.com/chroma-core/chroma/blob/main/examples/deployments/do-terraform/README.md)\n\n## 错误处理\n\n### 错误码体系\n\nChroma使用统一的错误码体系来分类不同类型的错误：\n\n| 错误码 | 含义 | 触发场景 |\n|-------|------|---------|\n| InvalidArgument | 无效参数 | 参数验证失败、ID不匹配 |\n| Internal | 内部错误 | Arrow格式错误、数据缺失 |\n| NotFound | 未找到 | 记录不存在 |\n| AlreadyExists | 已存在 | 重复创建 |\n\nSources: [rust/blockstore/src/arrow/root.rs:1-30](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n## 相关资源\n\n- 官方文档：https://docs.trychroma.com/\n- 社区Discord：https://discord.gg/MMeYNTmh3x\n- GitHub仓库：https://github.com/chroma-core/chroma\n- Homepage：https://www.trychroma.com/\n\n### 示例应用\n\nChroma仓库包含多个示例应用，展示了如何集成不同的AI服务：\n\n- **xAI集成**：展示如何使用xAI SDK进行文档问答\n- **Movies示例**：演示在Web应用中使用Chroma存储和检索电影数据\n- **部署示例**：提供Terraform配置用于云端部署\n\nSources: [examples/xai/README.md](https://github.com/chroma-core/chroma/blob/main/examples/xai/README.md), [sample_apps/movies/README.md](https://github.com/chroma-core/chroma/blob/main/sample_apps/movies/README.md)\n\n---\n\n\n\n## 安装与配置\n\n### Related Pages\n\nRelated topics: [Chroma项目概述](#page-overview)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [clients/python/pyproject.toml](https://github.com/chroma-core/chroma/blob/main/clients/python/pyproject.toml)\n- [clients/js/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/package.json)\n- [Dockerfile](https://github.com/chroma-core/chroma/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/chroma-core/chroma/blob/main/docker-compose.yml)\n \n\n# 安装与配置\n\n## 概述\n\nChroma 是一个开源的 AI 向量数据基础设施，提供向量存储、检索和混合搜索能力。本章节详细介绍 Chroma 的多种安装方式和配置选项，帮助开发者根据不同使用场景选择合适的部署方案。\n\nChroma 支持三种主要的部署模式：\n\n| 部署模式 | 适用场景 | 数据持久化 |\n|---------|---------|-----------|\n| Python 客户端嵌入模式 | 本地开发、原型验证 | 本地文件系统 |\n| 客户端-服务器模式 | 生产环境、多客户端访问 | 可配置存储后端 |\n| Docker 容器化部署 | 微服务架构、DevOps | Docker Volume |\n\nSources: [README.md](README.md)\n\n---\n\n## Python 客户端安装\n\n### 环境要求\n\nChroma Python 客户端支持 Python 3.8 及以上版本。建议使用虚拟环境进行安装以避免依赖冲突。\n\n### 安装方式\n\n#### 通过 pip 安装（推荐）\n\n```bash\npip install chromadb\n```\n\nSources: [README.md](README.md)\n\n#### 通过源码安装\n\n```bash\ngit clone https://github.com/chroma-core/chroma.git\ncd chroma\npip install -e .\n```\n\n#### 验证安装\n\n```python\nimport chromadb\nprint(chromadb.__version__)\n```\n\n### 核心依赖\n\nChroma Python 客户端的依赖管理通过 `pyproject.toml` 配置，主要依赖包括：\n\n| 依赖包 | 用途 |\n|-------|------|\n| `onnxruntime` | 向量计算引擎 |\n| `tokenizers` | 文本分词处理 |\n| `hnswlib` | HNSW 近似最近邻索引 |\n| `clickhouse-connect` | 可选：ClickHouse 后端支持 |\n\nSources: [clients/python/pyproject.toml](clients/python/pyproject.toml)\n\n---\n\n## JavaScript/TypeScript 客户端安装\n\n### 环境要求\n\n- Node.js 18.0 或更高版本\n- npm、yarn 或 pnpm 包管理器\n\n### 安装方式\n\n```bash\n# 使用 npm\nnpm install chromadb\n\n# 使用 yarn\nyarn add chromadb\n\n# 使用 pnpm\npnpm add chromadb\n```\n\nSources: [README.md](README.md)\n\n### 客户端包结构\n\n新版本 JavaScript 客户端 (`new-js`) 包含多个子包：\n\n| 包名 | 功能描述 |\n|-----|---------|\n| `@chroma-core/ai-embeddings-common` | 嵌入函数公共工具库 |\n| `@chroma-core/ai-embeddings` | AI 嵌入功能实现 |\n| `@chroma-core/chromadb` | 核心客户端实现 |\n\nSources: [clients/new-js/packages/ai-embeddings/common/README.md](clients/new-js/packages/ai-embeddings/common/README.md)\n\n### 基本使用示例\n\n```javascript\nimport { ChromaClient } from \"chromadb\";\n\nconst chroma = new ChromaClient();\nconst collection = await chroma.createCollection({ name: \"test-from-js\" });\n\nawait collection.add({\n ids: [\"test-id-1\"],\n embeddings: [[1, 2, 3, 4, 5]],\n documents: [\"test document\"],\n});\n```\n\nSources: [clients/new-js/packages/chromadb/README.md](clients/new-js/packages/chromadb/README.md)\n\n---\n\n## Docker 部署\n\n### 前置条件\n\n- Docker Engine 20.10 或更高版本\n- Docker Compose 2.0 或更高版本（可选）\n\n### 使用 Dockerfile 构建\n\nChroma 提供官方的 Dockerfile 用于构建自定义镜像：\n\n```dockerfile\nFROM python:3.9-slim\n\nWORKDIR /app\n\n# 安装系统依赖\nRUN apt-get update && apt-get install -y \\\n build-essential \\\n && rm -rf /var/lib/apt/lists/*\n\n# 复制应用代码\nCOPY . /app\n\n# 安装 Python 依赖\nRUN pip install --no-cache-dir -e .\n\n# 暴露端口\nEXPOSE 8000\n\n# 启动命令\nCMD [\"chroma\", \"run\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\n```\n\nSources: [Dockerfile](Dockerfile)\n\n### 使用 Docker Compose 编排\n\nDocker Compose 提供了快速启动完整 Chroma 服务的配置：\n\n```yaml\nversion: '3.8'\n\nservices:\n chroma:\n build: .\n ports:\n - \"8000:8000\"\n volumes:\n - chroma_data:/chroma/chroma_db_path\n environment:\n - CHROMA_SERVER_AUTH_CREDENTIALS=admin:password\n - CHROMA_SERVER_AUTH_PROVIDER=basic\n\nvolumes:\n chroma_data:\n```\n\nSources: [docker-compose.yml](docker-compose.yml)\n\n### 启动服务\n\n```bash\n# 仅启动 Chroma 服务\ndocker-compose up -d\n\n# 构建并启动\ndocker-compose up --build\n\n# 查看日志\ndocker-compose logs -f chroma\n\n# 停止服务\ndocker-compose down\n```\n\n---\n\n## 客户端-服务器模式配置\n\n当需要多客户端访问或生产环境部署时，使用 Chroma 的客户端-服务器模式。\n\n### 启动服务器\n\n```bash\n# 基础启动\nchroma run --path /chroma_db_path\n\n# 指定端口和主机\nchroma run --host 0.0.0.0 --port 8000 --path /chroma_db_path\n```\n\nSources: [README.md](README.md)\n\n### 服务器认证配置\n\nChroma 支持基于 Token 和 Basic Auth 两种认证方式（v0.4.7+）：\n\n| 认证类型 | 环境变量 | 说明 |\n|---------|---------|------|\n| Token 认证 | `CHROMA_SERVER_AUTH_CREDENTIALS` | 设置 Token 密钥 |\n| Basic Auth | `CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER` | 设置为 `chromadb.auth.basic.BasicAuthenticationServerProvider` |\n| CORS 配置 | `CHROMA_SERVER_CORS_ALLOWED_ORIGINS` | 允许的跨域来源 |\n\nSources: [examples/deployments/do-terraform/README.md](examples/deployments/do-terraform/README.md)\n\n### API 密钥配置\n\n对于 Chroma Cloud 服务，需要配置 API 密钥：\n\n```bash\nexport CHROMA_API_KEY=your-api-key\n```\n\nSources: [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md](clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md)\n\n### 连接客户端\n\n#### Python 客户端连接\n\n```python\nimport chromadb\n\n# 连接远程服务器\nclient = chromadb.HttpClient(\n host=\"http://localhost:8000\",\n headers={\"Authorization\": \"Bearer your-token\"}\n)\n\n# 使用 Cloud 服务\nclient = chromadb.Client(\n chroma_client_implementation=chromadb.auth.AuthenticatedClient,\n api_key=\"your-api-key\"\n)\n```\n\n#### JavaScript 客户端连接\n\n```javascript\nimport { ChromaClient } from \"chromadb\";\n\n// 连接远程服务器\nconst chroma = new ChromaClient({\n path: \"http://localhost:8000\"\n});\n```\n\n---\n\n## 环境变量配置\n\n### 完整环境变量列表\n\n| 环境变量 | 默认值 | 说明 |\n|---------|-------|------|\n| `CHROMA_DB_IMPL` | `duckdb+parquet` | 数据库实现类型 |\n| `CHROMA_SERVER_HOST` | `localhost` | 服务器主机地址 |\n| `CHROMA_SERVER_PORT` | `8000` | 服务器端口 |\n| `CHROMA_SERVER_CORS_ALLOWED_ORIGINS` | `*` | 允许的 CORS 来源 |\n| `CHROMA_SERVER_AUTH_CREDENTIALS` | - | 认证凭证 |\n| `CHROMA_SERVER_AUTH_PROVIDER` | - | 认证提供者 |\n| `CHROMA_API_KEY` | - | Cloud API 密钥 |\n\nSources: [README.md](README.md), [sample_apps/movies/README.md](sample_apps/movies/README.md)\n\n### 示例：生产环境配置\n\n```bash\n# 环境变量配置示例\nexport CHROMA_SERVER_HOST=0.0.0.0\nexport CHROMA_SERVER_PORT=8000\nexport CHROMA_SERVER_CORS_ALLOWED_ORIGINS=\"https://your-app.com\"\nexport CHROMA_SERVER_AUTH_CREDENTIALS=\"your-secure-password\"\nexport CHROMA_SERVER_AUTH_PROVIDER=\"chromadb.auth.basic.BasicAuthenticationServerProvider\"\n```\n\n---\n\n## 嵌入函数配置\n\n### 内置嵌入函数\n\nChroma 提供多种内置嵌入函数，支持不同的 AI 提供商：\n\n| 提供商 | 模型 | 配置参数 |\n|-------|-----|---------|\n| OpenAI | `text-embedding-ada-002` | `api_key_env_var`, `model_name` |\n| Google Docs | - | `credentials`, `token` |\n| xAI | Qwen3-Embedding-0.6B | `api_key_env_var`, `model`, `task` |\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](chromadb/utils/embedding_functions/schemas/README.md), [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md](clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md)\n\n### 嵌入函数配置验证\n\nChroma 使用 JSON Schema 对嵌入函数配置进行验证，确保跨语言兼容性：\n\n```python\nfrom chromadb.utils.embedding_functions.schemas import validate_config\n\n# 验证 OpenAI 配置\nconfig = {\n \"api_key_env_var\": \"CHROMA_OPENAI_API_KEY\",\n \"model_name\": \"text-embedding-ada-002\"\n}\nvalidate_config(config, \"openai\")\n```\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](chromadb/utils/embedding_functions/schemas/README.md)\n\n---\n\n## 快速入门示例\n\n### 本地模式（Python）\n\n```python\nimport chromadb\n\n# 创建客户端（本地模式）\nclient = chromadb.PersistentClient(path=\"./chroma_db\")\n\n# 创建集合\ncollection = client.create_collection(name=\"my_collection\")\n\n# 添加数据\ncollection.add(\n documents=[\"第一个文档\", \"第二个文档\", \"第三个文档\"],\n ids=[\"id1\", \"id2\", \"id3\"],\n metadatas=[{\"source\": \"docs\"}, {\"source\": \"docs\"}, {\"source\": \"api\"}]\n)\n\n# 查询数据\nresults = collection.query(\n query_texts=[\"查询文本\"],\n n_results=2\n)\n\nprint(results)\n```\n\n### 服务器模式（Python）\n\n```python\nimport chromadb\n\n# 连接服务器\nclient = chromadb.HttpClient(host=\"http://localhost:8000\")\n\n# 后续操作与本地模式相同\ncollection = client.get_collection(name=\"my_collection\")\nresults = collection.query(\n query_texts=[\"查询文本\"],\n n_results=2,\n where={\"source\": \"docs\"} # 元数据过滤\n)\n```\n\nSources: [README.md](README.md)\n\n---\n\n## 部署架构\n\n### 单节点部署架构\n\n```mermaid\ngraph TD\n A[Client Application] -->|HTTP API| B[Chroma Server]\n B --> C[DuckDB + Parquet]\n B --> D[HNSW Index]\n C --> E[Persistent Storage]\n D --> E\n \n F[Embedding Function] -->|Compute Embeddings| B\n G[OpenAI API] -->|Optional| F\n```\n\n### Docker 部署架构\n\n```mermaid\ngraph TD\n A[External Clients] -->|HTTP| B[Docker Container]\n B --> C[Chroma Server]\n C --> D[(DuckDB)]\n C --> E[HNSW Index]\n D --> F[Volume: chroma_data]\n E --> F\n \n G[Embedding Service] -->|Compute| C\n```\n\n### 生产环境部署架构\n\n```mermaid\ngraph LR\n A[Web App] -->|API Requests| B[Load Balancer]\n B --> C1[Chroma Node 1]\n B --> C2[Chroma Node 2]\n B --> C3[Chroma Node N]\n \n C1 --> D[(Shared Storage)]\n C2 --> D\n C3 --> D\n \n D --> E[S3 / NFS]\n```\n\n---\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 连接超时 | 服务未启动或端口错误 | 确认服务运行状态和端口配置 |\n| 认证失败 | Token 或 Basic Auth 配置错误 | 检查环境变量配置 |\n| 嵌入维度不匹配 | 不同嵌入函数生成的向量维度不同 | 确保同一集合使用相同的嵌入函数 |\n| 存储空间不足 | Parquet 文件过大 | 配置数据分片或清理旧数据 |\n\n### 日志查看\n\n```bash\n# Docker 环境查看日志\ndocker-compose logs chroma\n\n# 直接运行查看实时日志\nchroma run --path /chroma_db_path --verbose\n```\n\n---\n\n## 相关资源\n\n- [官方文档](https://docs.trychroma.com/)\n- [GitHub 仓库](https://github.com/chroma-core/chroma)\n- [Discord 社区](https://discord.gg/MMeYNTmh3x)\n- [Chroma Cloud](https://trychroma.com/)\n\n---\n\n\n\n## 系统架构\n\n### Related Pages\n\nRelated topics: [数据流与处理流程](#page-data-flow), [向量索引系统](#page-vector-index), [存储系统](#page-storage)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/frontend/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/frontend/src/lib.rs)\n- [rust/worker/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/lib.rs)\n- [go/pkg/sysdb/coordinator/coordinator.go](https://github.com/chroma-core/chroma/blob/main/go/pkg/sysdb/coordinator/coordinator.go)\n- [idl/chromadb/proto/chroma.proto](https://github.com/chroma-core/chroma/blob/main/idl/chromadb/proto/chroma.proto)\n- [rust/system/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/system/src/lib.rs)\n \n\n# 系统架构\n\n## 概述\n\nChroma 是一个开源的 AI 向量数据库，专为存储和检索高维向量数据而设计。系统采用分布式架构，包含多个核心组件协同工作，以提供高效的向量存储、索引和查询能力。\n\nChroma 的系统架构遵循微服务设计原则，将不同的功能模块分离为独立的服务组件，通过 gRPC 协议进行进程间通信。系统支持多租户架构，能够在单一部署中服务多个 tenants 和 databases。\n\n## 系统架构图\n\n```mermaid\ngraph TD\n subgraph Client[\"客户端层\"]\n JS[JavaScript Client]\n Python[Python Client]\n end\n\n subgraph Frontend[\"前端服务\"]\n API[REST/gRPC API]\n Auth[认证模块]\n end\n\n subgraph Worker[\"Worker 服务\"]\n QueryEngine[查询引擎]\n Indexing[索引服务]\n Blockstore[块存储]\n end\n\n subgraph Coordinator[\"协调器\"]\n SysDB[系统数据库]\n TenantMgr[租户管理]\n CollectionMgr[集合管理]\n end\n\n subgraph Storage[\"存储层\"]\n Arrow[Arrow Blockfiles]\n HNSW[HNSW 索引]\n Log[预写日志]\n end\n\n JS --> API\n Python --> API\n API --> Auth\n Auth --> QueryEngine\n QueryEngine --> Indexing\n Indexing --> Blockstore\n Coordinator --> SysDB\n QueryEngine --> Coordinator\n Blockstore --> Arrow\n Indexing --> HNSW\n```\n\n## 核心组件\n\n### 前端服务 (Frontend)\n\n前端服务是 Chroma 系统的入口点，负责处理客户端请求并进行初步验证。源代码显示前端模块采用 Rust 实现，提供了核心的 API 接口。\n\n**主要职责：**\n- 接收并验证客户端请求\n- 处理认证和授权\n- 请求路由和负载均衡\n- 返回标准化的响应格式\n\n**模块位置：** `rust/frontend/src/lib.rs`\n\n### Worker 服务\n\nWorker 是 Chroma 系统中的核心计算节点，负责执行实际的向量操作。每个 Worker 节点可以独立处理查询和索引任务。\n\n**主要职责：**\n- 执行向量相似度搜索\n- 管理 HNSW 索引\n- 处理元数据过滤\n- 存储和检索块数据\n\n**核心子模块：**\n\n| 模块 | 功能 | 源码位置 |\n|------|------|----------|\n| 查询引擎 | 处理向量查询请求 | `rust/worker/src/lib.rs` |\n| 索引服务 | 管理 HNSW/SPANN 索引 | `rust/index/src/` |\n| 块存储 | 持久化向量数据 | `rust/blockstore/src/` |\n\n**块存储架构：**\n\n```mermaid\ngraph LR\n subgraph Blockfile[\"Blockfile 结构\"]\n Header[文件头]\n Body[数据体]\n Footer[文件尾]\n end\n\n subgraph ArrowFormat[\"Arrow IPC 格式\"]\n RecordBatch[Record Batch]\n Schema[Schema 元数据]\n end\n\n Header --> RecordBatch\n RecordBatch --> Body\n Body --> Footer\n```\n\nChroma 使用 Apache Arrow 格式作为底层存储格式，支持高效的列式数据存储和读取。Blockfile 是数据存储的基本单元，包含文件头、数据体和文件尾三部分。\n\nSources: [rust/blockstore/src/arrow/root.rs:1-30](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n### 协调器 (Coordinator)\n\n协调器是系统的中央控制组件，使用 Go 语言实现。它负责管理系统的元数据和全局状态。\n\n**主要职责：**\n- 管理租户和数据库元数据\n- 协调集合的创建和删除\n- 维护系统拓扑信息\n- 处理分布式事务\n\n**协调器结构：**\n\n| 组件 | 功能 | 描述 |\n|------|------|------|\n| SysDB | 系统数据库 | 存储租户、数据库、集合的元数据 |\n| TenantManager | 租户管理器 | 管理租户的生命周期 |\n| CollectionManager | 集合管理器 | 管理集合的创建、删除和分片 |\n\nSources: [go/pkg/sysdb/coordinator/coordinator.go:1-50](https://github.com/chroma-core/chroma/blob/main/go/pkg/sysdb/coordinator/coordinator.go)\n\n## 通信协议\n\n### gRPC 接口定义\n\nChroma 使用 Protocol Buffers 定义服务接口，支持类型安全的跨语言通信。\n\n**核心服务定义：**\n\n```protobuf\n// 来源: idl/chromadb/proto/chroma.proto\nservice Chroma {\n rpc CreateCollection(CreateCollectionRequest) returns (CreateCollectionResponse);\n rpc GetCollection(GetCollectionRequest) returns (GetCollectionResponse);\n rpc DeleteCollection(DeleteCollectionRequest) returns (DeleteCollectionResponse);\n rpc Add(AddRequest) returns (AddResponse);\n rpc Get(GetRequest) returns (GetResponse);\n rpc Query(QueryRequest) returns (QueryResponse);\n}\n```\n\n**查询请求参数：**\n\n| 参数名 | 类型 | 描述 |\n|--------|------|------|\n| `query_embeddings` | Vec\\\\> | 查询向量 |\n| `n_results` | int | 返回结果数量 |\n| `where` | Where | 元数据过滤条件 |\n| `include` | Vec\\ | 返回包含的字段 |\n\nSources: [idl/chromadb/proto/chroma.proto:1-100](https://github.com/chroma-core/chroma/blob/main/idl/chromadb/proto/chroma.proto)\n\n### 消息类型\n\n系统定义了丰富的消息类型用于客户端与服务端之间的数据交换。\n\n```mermaid\nclassDiagram\n class GetRequest {\n +collection_id: String\n +ids: Vec~String~\n +where: Option~Where~\n +include: Vec~String~\n }\n class QueryRequest {\n +collection_id: String\n +query_embeddings: Vec~Vec~float~~\n +n_results: int\n +where: Option~Where~\n +query_texts: Option~Vec~String~~\n }\n class GetResponse {\n +ids: Vec~String~\n +embeddings: Option~Vec~Vec~float~~\n +documents: Option~Vec~String~\n +metadatas: Option~Vec~Metadata~\n }\n```\n\n## 数据模型\n\n### 集合 (Collection)\n\n集合是 Chroma 中的基本数据组织单位，每个集合包含一组相关的向量数据。\n\n```rust\n// 集合属性\nstruct Collection {\n id: CollectionUuid, // 唯一标识符\n name: String, // 集合名称\n tenant_id: String, // 租户标识\n database_name: String, // 数据库名称\n dimension: Option, // 向量维度\n get_index: Option, // 索引配置\n metadata: Option,\n created_at: Timestamp,\n version: i32,\n}\n```\n\nSources: [rust/types/src/collection_schema.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n### 索引配置\n\nChroma 支持多种索引类型以优化查询性能。\n\n| 索引类型 | 描述 | 适用场景 |\n|----------|------|----------|\n| HNSW | 分层可导航小世界图 | 高精度向量搜索 |\n| SPANN | 基于磁盘的向量索引 | 超大规模向量数据 |\n| String Inverted Index | 字符串倒排索引 | 元数据过滤 |\n| Vector Index | 向量索引 | 相似度搜索 |\n\n**向量索引配置示例：**\n\n```rust\nVectorIndexConfig {\n space: Some(Space::Cosine), // 距离度量\n embedding_function: None, // embedding 函数\n source_key: None, // 源 key\n hnsw: None, // HNSW 参数\n spann: None, // SPANN 参数\n}\n```\n\nSources: [rust/types/src/collection_schema.rs:100-150](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n### 过滤条件\n\nChroma 支持丰富的元数据过滤功能。\n\n```mermaid\ngraph TD\n A[Where 过滤条件] --> B[MetadataComparison]\n A --> C[WhereDocumentOperator]\n B --> D[Primitive]\n B --> E[Set Operation]\n D --> F[Equal / NotEqual]\n D --> G[Greater / Less]\n D --> H[Contains / StartsWith]\n C --> I[Contains / NotContains]\n C --> J[Regex / NotRegex]\n```\n\n**支持的比较操作：**\n\n| 操作类型 | 描述 | 示例 |\n|----------|------|------|\n| `$eq` | 等于 | `{\"key\": {\"$eq\": \"value\"}}` |\n| `$ne` | 不等于 | `{\"key\": {\"$ne\": 10}}` |\n| `$gt` | 大于 | `{\"key\": {\"$gt\": 5}}` |\n| `$lt` | 小于 | `{\"key\": {\"$lt\": 100}}` |\n| `$gte` | 大于等于 | `{\"key\": {\"$gte\": 1}}` |\n| `$lte` | 小于等于 | `{\"key\": {\"$lte\": 10}}` |\n\nSources: [rust/types/src/metadata.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n\n## 系统拓扑\n\nChroma 支持多区域部署，允许在不同云提供商的区域中部署 Worker 节点。\n\n```mermaid\ngraph TD\n subgraph Topology[\"系统拓扑\"]\n subgraph Region1[\"区域 1\"]\n WR1[Worker Region 1]\n end\n subgraph Region2[\"区域 2\"]\n WR2[Worker Region 2]\n end\n subgraph RegionN[\"区域 N\"]\n WR3[Worker Region N]\n end\n end\n\n Coordinator --> WR1\n Coordinator --> WR2\n Coordinator --> WR3\n```\n\n**拓扑配置结构：**\n\n```rust\npub struct Topology {\n pub name: TopologyName, // 拓扑名称\n pub regions: Vec, // 包含的区域列表\n pub config: T, // 拓扑配置\n}\n\npub struct ProviderRegion {\n pub name: RegionName, // 区域名称\n pub provider: String, // 云提供商 (aws/gcp/azure)\n pub region: String, // 区域标识\n pub config: T, // 区域配置\n}\n```\n\nSources: [rust/types/src/topology.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n\n## 请求处理流程\n\n### 客户端请求流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Frontend\n participant Coordinator\n participant Worker\n participant Storage\n\n Client->>Frontend: 发起请求\n Frontend->>Frontend: 认证和验证\n Frontend->>Coordinator: 获取元数据\n Coordinator->>Frontend: 返回集合信息\n Frontend->>Worker: 路由查询请求\n Worker->>Worker: 执行向量搜索\n Worker->>Storage: 读取块数据\n Storage->>Worker: 返回数据\n Worker->>Frontend: 返回结果\n Frontend->>Client: 响应结果\n```\n\n### 查询请求处理\n\n1. **请求验证**：Frontend 接收并验证查询请求参数\n2. **元数据获取**：从 Coordinator 获取集合的配置信息\n3. **索引定位**：根据查询条件确定需要扫描的索引\n4. **向量搜索**：在 Worker 节点上执行 HNSW 或其他索引搜索\n5. **结果聚合**：合并多个 Worker 的结果并排序\n6. **元数据过滤**：应用 where 条件过滤最终结果\n7. **响应构建**：根据 include 参数构建响应数据\n\nSources: [rust/system/src/lib.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/system/src/lib.rs)\n\n## 部署架构\n\n### 单一节点部署\n\n在开发和测试环境中，Chroma 可以以单节点模式运行，所有组件运行在同一个进程中。\n\n```yaml\n# 单节点配置示例\nchroma:\n server:\n host: \"0.0.0.0\"\n port: 8000\n storage:\n type: \"local\"\n path: \"/chroma_db\"\n```\n\n### 分布式部署\n\n生产环境推荐使用分布式架构部署：\n\n| 组件 | 副本数 | 职责 |\n|------|--------|------|\n| Frontend | 2-3 | 高可用 API 服务 |\n| Coordinator | 3 | 高可用元数据管理 |\n| Worker | N | 弹性扩展的计算节点 |\n\n```mermaid\ngraph TB\n subgraph LoadBalancer[\"负载均衡器\"]\n LB[Load Balancer]\n end\n\n subgraph FrontendCluster[\"Frontend 集群\"]\n FE1[Frontend 1]\n FE2[Frontend 2]\n end\n\n subgraph CoordinatorCluster[\"Coordinator 集群\"]\n C1[Coordinator 1]\n C2[Coordinator 2]\n C3[Coordinator 3]\n end\n\n subgraph WorkerCluster[\"Worker 集群\"]\n W1[Worker 1]\n W2[Worker 2]\n W3[Worker N]\n end\n\n LB --> FE1\n LB --> FE2\n FE1 --> C1\n FE2 --> C1\n C1 <--> C2\n C2 <--> C3\n FE1 --> W1\n FE1 --> W2\n FE2 --> W2\n FE2 --> W3\n```\n\n## 关键技术特性\n\n### Arrow 存储格式\n\nChroma 使用 Apache Arrow 作为底层存储格式，带来以下优势：\n\n- **列式存储**：支持高效的列投影操作\n- **零拷贝读取**：避免不必要的数据复制\n- **统一数据接口**：支持多种编程语言\n- **压缩友好**：便于应用压缩算法\n\n```rust\n// Arrow Blockfile 读取流程\nlet arrow_reader = arrow::ipc::reader::FileReader::try_new(&mut cursor, None);\nlet record_batch = reader.next(); // 读取 Record Batch\nlet block_ids = Self::block_ids_from_record_batch(&record_batch, version);\n```\n\nSources: [rust/blockstore/src/arrow/root.rs:20-40](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n### 多语言客户端支持\n\nChroma 提供多语言 SDK 支持：\n\n| 语言 | 包名 | 源码位置 |\n|------|------|----------|\n| Python | `chromadb` | `clients/python/` |\n| JavaScript | `chromadb` | `clients/js/` |\n| Go | `chromadb-go` | `clients/go/` |\n\n**Python 客户端示例：**\n\n```python\nfrom chromadb import ChromaClient\n\nclient = ChromaClient()\ncollection = client.create_collection(\"my_collection\")\ncollection.add(\n ids=[\"1\", \"2\"],\n embeddings=[[1.0, 2.0], [3.0, 4.0]],\n documents=[\"doc1\", \"doc2\"]\n)\nresults = collection.query(\n query_embeddings=[[1.0, 2.0]],\n n_results=1\n)\n```\n\nSources: [clients/new-js/packages/chromadb/README.md:1-50](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/README.md)\n\n## 总结\n\nChroma 的系统架构采用了现代分布式系统的设计理念，通过将前端服务、Worker 节点和协调器分离，实现了系统的可扩展性和高可用性。Arrow 存储格式的应用使得数据操作更加高效，而 gRPC 和 Protocol Buffers 的使用则保证了跨语言的互操作性。\n\n---\n\n\n\n## 数据流与处理流程\n\n### Related Pages\n\nRelated topics: [系统架构](#page-architecture), [查询执行引擎](#page-query-execution)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/blockstore/src/arrow/root.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n- [rust/types/src/collection_schema.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n- [rust/types/src/execution/operator.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/execution/operator.rs)\n- [rust/types/src/topology.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n- [rust/blockstore/src/arrow/block/types.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n- [rust/types/src/metadata.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n- [rust/types/src/sparse_posting_block.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n- [rust/types/src/api_types.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/api_types.rs)\n- [rust/worker/src/compactor/scheduler.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/compactor/scheduler.rs)\n- [rust/blockstore/src/arrow/provider.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n- [rust/index/src/spann/types.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n- [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n- [rust/chroma/README.md](https://github.com/chroma-core/chroma/blob/main/rust/chroma/README.md)\n- [rust/wal3/README.md](https://github.com/chroma-core/chroma/blob/main/rust/wal3/README.md)\n \n\n# 数据流与处理流程\n\n## 概述\n\nChroma 是一个开源的 AI 矢量数据库，其核心架构围绕数据存储、索引构建和查询处理三个主要环节构建。数据流与处理流程涵盖从数据摄入到查询响应的完整生命周期，包括数据编码、块存储、索引管理、执行计划生成和多阶段查询处理等关键环节。\n\nChroma 的数据流设计遵循分布式系统原则，支持多租户、多数据库架构，并通过拓扑（Topology）管理跨区域的数据分布。Sources: [rust/types/src/topology.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n\n## 核心架构组件\n\n### 系统层级结构\n\n```mermaid\ngraph TD\n A[API Layer] --> B[Worker Service]\n B --> C[Execution Engine]\n C --> D[Index Layer]\n D --> E[Blockstore]\n E --> F[Arrow Storage]\n \n G[SysDB] --> B\n H[Log Service] --> B\n I[Compactor Scheduler] --> B\n```\n\nChroma 的处理流程涉及多个核心子系统的协作：\n\n| 组件 | 职责 | 主要文件 |\n|------|------|----------|\n| API Layer | 接收请求、参数验证 | rust/types/src/api_types.rs |\n| Worker Service | 任务编排、执行调度 | rust/worker/src/execution/orchestration/mod.rs |\n| Execution Engine | 执行计划、算子处理 | rust/types/src/execution/operator.rs |\n| Index Layer | 矢量索引、HNSW/SPANN | rust/index/src/spann/types.rs |\n| Blockstore | 数据块存储、Arrow IPC | rust/blockstore/src/arrow/provider.rs |\n| Compactor | 压缩合并、垃圾回收 | rust/worker/src/compactor/scheduler.rs |\n\n## 数据摄入流程\n\n### 写入请求处理\n\n客户端通过 API 提交数据写入请求，数据首先经过验证和预处理，然后进入写入流程。Chroma 支持批量写入操作，通过 BlockfileWriter 实现数据的有序或无序写入。 Sources: [rust/blockstore/src/arrow/provider.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n```mermaid\ngraph LR\n A[Add Request] --> B[Validation]\n B --> C[Embedding Generation]\n C --> D[Schema Validation]\n D --> E[BlockfileWriter]\n E --> F[Arrow IPC Format]\n F --> G[Block Storage]\n```\n\n### Blockfile 写入模式\n\nBlockfileWriter 支持两种写入顺序模式：\n\n| 模式 | 说明 | 使用场景 |\n|------|------|----------|\n| Ordered | 有序写入，保证数据顺序 | 需要精确顺序的查询 |\n| Unordered | 无序写入，更高吞吐 | 批量导入、高吞吐写入 |\n\n创建 Blockfile 时可以指定 `fork_from` 参数从现有 Blockfile 分叉，这对于快照和分支操作至关重要。 Sources: [rust/blockstore/src/arrow/provider.rs:50-100](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n## 索引构建与存储\n\n### Schema 与索引配置\n\nChroma 使用 Schema 定义集合的数据结构，支持创建多种类型的索引：\n\n```rust\n// 索引配置示例\nSchema::default()\n .create_index(None, VectorIndexConfig {\n space: Some(Space::Cosine),\n embedding_function: None,\n source_key: None,\n hnsw: None,\n spann: None,\n }.into())?\n .create_index(Some(\"category\"), StringInvertedIndexConfig {}.into())?;\n```\n\nSources: [rust/types/src/collection_schema.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n### Arrow IPC 存储格式\n\nChroma 使用 Apache Arrow IPC 格式存储数据块，具有以下特点：\n\n- **内存映射支持**：允许高效访问大型数据集\n- **类型安全**：强类型列式存储\n- **跨语言兼容**：可与其他 Arrow 生态工具互操作\n\nBlock 存储包含元数据校验，确保数据完整性：\n\n```rust\npub enum ArrowLayoutVerificationError {\n BufferLengthNotAligned,\n NoRecordBatches,\n MultipleRecordBatches,\n InvalidMessageType,\n RecordBatchDecodeError,\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n### Root 管理与版本控制\n\nRoot 是 Chroma 中的核心存储单元，每个 Root 包含版本信息和块 ID 列表：\n\n```rust\npub(super) fn get_all_block_ids_from_bytes(\n bytes: &[u8],\n id: Uuid,\n) -> Result, FromBytesError> {\n let arrow_reader = arrow::ipc::reader::FileReader::try_new(&mut cursor, None);\n // 版本验证和块 ID 提取\n}\n```\n\nSources: [rust/blockstore/src/arrow/root.rs:1-60](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n## 执行引擎架构\n\n### 执行计划结构\n\nChroma 的查询执行采用算子图模型，每个查询被编译为执行计划：\n\n```mermaid\ngraph TD\n A[Query Input] --> B[Plan Generation]\n B --> C[Operator Tree]\n C --> D[Execution]\n D --> E[Result Assembly]\n E --> F[Response]\n```\n\n执行计划定义了查询的完整执行逻辑，包括过滤、投影、排序等操作。 Sources: [rust/types/src/execution/plan.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/types/src/execution/plan.rs)\n\n### 搜索算子与结果处理\n\n搜索操作返回 `SearchPayloadResult`，包含匹配的记录列表：\n\n```rust\n#[derive(Clone, Debug, Default)]\npub struct SearchPayloadResult {\n pub records: Vec,\n}\n```\n\n每个搜索结果批次还包含日志拉取字节数指标，用于内部性能监控。 Sources: [rust/types/src/execution/operator.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/execution/operator.rs)\n\n## 查询处理流程\n\n### 查询请求结构\n\n```mermaid\nsequenceDiagram\n Client->>API: Query Request\n API->>Validation: Validate Parameters\n Validation->>Execution: Create Execution Plan\n Execution->>Index: Search Index\n Index->>Execution: Merge Results\n Execution->>API: SearchPayloadResult\n API->>Client: Query Response\n```\n\n### Include 列表与响应字段\n\n查询时可以通过 `include` 参数指定返回的字段：\n\n```rust\npub enum Include {\n Distance,\n Document,\n Embedding,\n Metadata,\n Uri,\n}\n\npub struct IncludeList(pub Vec);\n\nimpl IncludeList {\n pub fn default_query() -> Self {\n Self(vec![\n Include::Document,\n Include::Metadata,\n Include::Distance,\n ])\n }\n}\n```\n\nSources: [rust/types/src/api_types.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/types/src/api_types.rs)\n\n### 元数据过滤\n\nChroma 支持丰富的元数据查询操作符：\n\n| 操作符类型 | 说明 | 示例 |\n|-----------|------|------|\n| `Contains` | 文档包含字符串 | `{\"$contains\": \"keyword\"}` |\n| `NotContains` | 文档不包含字符串 | `{\"$not_contains\": \"spam\"}` |\n| `Regex` | 正则表达式匹配 | `{\"$regex\": \"^[A-Z].*\"}` |\n| `NotRegex` | 正则表达式不匹配 | `{\"$not_regex\": \"^test\"}` |\n\nSources: [rust/types/src/metadata.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n\n## 矢量索引系统\n\n### SPANN 索引\n\nSPANN (Scalable PArtitioning Algorithm for Approximate Nearest Neighbor) 是 Chroma 的稀疏矢量索引实现：\n\n```rust\npub struct SpannPosting {\n pub doc_offset_id: u32,\n pub doc_embedding: Vec,\n}\n\npub struct SpannIndexReader<'me> {\n pub posting_lists: BlockfileReader<'me, u32, SpannPostingList<'me>>,\n pub hnsw_index: HnswIndexRef,\n pub versions_map: BlockfileReader<'me, u32, u32>,\n pub dimensionality: usize,\n pub adaptive_search_nprobe: bool,\n}\n```\n\nSources: [rust/index/src/spann/types.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### 稀疏 Posting Block\n\n稀疏索引使用 DirectoryBlock 管理 posting 列表的目录信息：\n\n```text\nbody = [ max_offset: u32 LE, max_weight: f32 LE ] × num_entries\n```\n\n目录块的 `max_weight` 存储维度级别的最大权重，用于早期术语剪枝。 Sources: [rust/types/src/sparse_posting_block.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n\n## 分布式拓扑管理\n\n### ProviderRegion 结构\n\nChroma 使用拓扑管理跨区域的数据分布：\n\n```rust\npub struct ProviderRegion {\n pub name: RegionName,\n pub provider: String, // 如 \"aws\", \"gcp\"\n pub region: String, // 如 \"us-east-1\"\n pub config: T,\n}\n```\n\n每个 ProviderRegion 具有唯一名称，支持云提供商的区域级配置。 Sources: [rust/types/src/topology.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n\n### Topology 结构\n\n```rust\npub struct Topology {\n pub name: TopologyName,\n regions: Vec,\n pub config: T,\n}\n```\n\nTopology 聚合多个 ProviderRegion，支持全局视角的数据分布管理。 Sources: [rust/types/src/topology.rs:80-150](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n\n## 压缩与后台处理\n\n### Compactor Scheduler\n\nCompactor 负责数据的压缩合并和垃圾回收：\n\n```mermaid\ngraph TD\n A[Scheduler] --> B[Job Queue]\n A --> C[Assignment Policy]\n B --> D[Collections]\n D --> E[Compaction Jobs]\n E --> F[Log Truncation]\n F --> G[Garbage Collection]\n```\n\n核心调度参数：\n\n| 参数 | 说明 |\n|------|------|\n| `max_concurrent_jobs` | 最大并发任务数 |\n| `min_compaction_size` | 最小压缩块大小 |\n| `job_expiry_seconds` | 任务过期时间 |\n| `max_failure_count` | 最大失败重试次数 |\n\nSources: [rust/worker/src/compactor/scheduler.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/compactor/scheduler.rs)\n\n### WAL3 日志系统\n\nChroma 使用 WAL3 (Write-Ahead Log 3) 管理写入日志：\n\n```text\nwal3/\n├── log/Bucket=XXXXX/FragmentSeqNo=XXXXX.parquet\n├── manifest/MANIFEST\n├── snapshot/SNAPSHOT.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n└── garbage/GARBAGE\n```\n\nWAL3 的写入路径：\n\n1. Writer 调用 `push_work` 提交工作到 fragment manager\n2. Fragment manager 批量处理达到阈值时分配 fragment\n3. 数据刷新到对象存储，调用 `assign_timestamp` 更新 manifest\n4. 创建 manifest 变更记录\n\nSources: [rust/wal3/README.md:1-100](https://github.com/chroma-core/chroma/blob/main/rust/wal3/README.md)\n\n## 错误处理机制\n\n### ChromaError trait\n\n所有 Chroma 错误类型实现 `ChromaError` trait：\n\n```rust\npub enum ErrorCodes {\n Internal, // 内部错误\n InvalidArgument, // 参数错误\n NotFound, // 资源未找到\n AlreadyExists, // 资源已存在\n // ... 其他错误码\n}\n```\n\n错误映射示例：\n\n```rust\nmatch self {\n BlockLoadError::IOError(_) => ErrorCodes::Internal,\n BlockLoadError::ArrowError(_) => ErrorCodes::Internal,\n BlockLoadError::NoRecordBatches => ErrorCodes::Internal,\n BlockLoadError::CacheError(_) => ErrorCodes::Internal,\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:80-120](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n## 完整数据流图\n\n```mermaid\ngraph TD\n subgraph Client\n A[HTTP/SDK Request]\n end\n \n subgraph API\n B[Request Validation]\n C[Parameter Parsing]\n end\n \n subgraph Processing\n D[Execution Orchestration]\n E[Plan Generation]\n F[Operator Execution]\n end\n \n subgraph Storage\n G[Blockfile Provider]\n H[Arrow IPC Storage]\n I[WAL3 Log]\n end\n \n subgraph Index\n J[Vector Index HNSW/SPANN]\n K[Inverted Index]\n end\n \n subgraph Background\n L[Compactor Scheduler]\n M[Garbage Collection]\n end\n \n A --> B --> C --> D\n D --> E --> F\n F --> J\n F --> K\n G --> H\n G --> I\n L --> M\n M --> H\n \n F --> N[Query Response]\n```\n\n## 总结\n\nChroma 的数据流与处理流程涵盖从客户端请求到持久化存储的完整链路。核心特点包括：\n\n1. **分层架构**：清晰的 API、执行引擎、存储和索引层分离\n2. **Arrow IPC 格式**：高效、跨语言的列式存储\n3. **多种索引支持**：HNSW 矢量索引、SPANN 稀疏索引、倒排索引\n4. **分布式拓扑**：支持多区域、多租户的数据分布\n5. **后台处理**：压缩调度、垃圾回收保证系统健康\n\nSources: [README.md:1-50](https://github.com/chroma-core/chroma/blob/main/README.md), [rust/chroma/README.md:1-80](https://github.com/chroma-core/chroma/blob/main/rust/chroma/README.md)\n\n---\n\n\n\n## 向量索引系统\n\n### Related Pages\n\nRelated topics: [查询执行引擎](#page-query-execution), [存储系统](#page-storage)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/index/src/hnsw.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/hnsw.rs)\n- [rust/index/src/spann.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann.rs)\n- [rust/index/src/quantization/mod.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/quantization/mod.rs)\n- [rust/index/src/sparse/mod.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/sparse/mod.rs)\n- [rust/segment/src/local_hnsw.rs](https://github.com/chroma-core/chroma/blob/main/rust/segment/src/local_hnsw.rs)\n- [rust/index/src/spann/types.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n- [rust/blockstore/src/arrow/provider.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n \n\n# 向量索引系统\n\n## 概述\n\nChroma的向量索引系统是一个多层次、高性能的近似最近邻（ANN）搜索基础设施，旨在支持大规模向量数据的存储、索引和检索。该系统采用多种索引策略，包括HNSW（分层可导航小世界图）、Spann（稀疏向量索引）、量化（Quantization）以及稀疏索引模块，为不同的搜索场景提供优化的性能和精度平衡。\n\n向量索引系统在Chroma架构中处于核心地位，负责将高维向量数据组织成可高效查询的索引结构，支持余弦距离、点积、欧几里得距离等多种距离函数。\n\nSources: [rust/index/src/hnsw.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/index/src/hnsw.rs)\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"索引层\"\n HNSW[HNSW索引模块]\n Spann[Spann稀疏索引]\n Quantization[量化模块]\n SparseIndex[稀疏索引模块]\n end\n \n subgraph \"存储层\"\n BlockfileProvider[BlockfileProvider]\n BlockfileWriter[BlockfileWriter]\n ArrowOrdered[ArrowOrderedBlockfileWriter]\n ArrowUnordered[ArrowUnorderedBlockfileWriter]\n end\n \n subgraph \"核心组件\"\n HnswIndexProvider[HnswIndexProvider]\n HnswIndexRef[HnswIndexRef]\n SpannIndexReader[SpannIndexReader]\n SpannIndexWriter[SpannIndexWriter]\n end\n \n HNSW --> HnswIndexProvider\n HNSW --> HnswIndexRef\n Spann --> SpannIndexReader\n Spann --> SpannIndexWriter\n BlockfileProvider --> BlockfileWriter\n BlockfileWriter --> ArrowOrdered\n BlockfileWriter --> ArrowUnordered\n HnswIndexProvider --> BlockfileProvider\n```\n\n### 索引类型对比\n\n| 索引类型 | 用途 | 适用场景 | 核心数据结构 |\n|---------|------|---------|-------------|\n| HNSW | 高效ANN搜索 | 稠密向量、精确排序 | 分层图结构 |\n| Spann | 稀疏向量索引 | 稀疏嵌入、混合搜索 | Posting List + HNSW |\n| Quantization | 向量压缩 | 大规模数据、内存受限 | PQ/SQ量化 |\n| Sparse Index | 稀疏特征索引 | 关键词搜索、推荐系统 | 倒排索引 |\n\nSources: [rust/index/src/spann/types.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## HNSW索引模块\n\n### HNSW算法概述\n\nHNSW（Hierarchical Navigable Small World）是一种基于图的近似最近邻搜索算法，通过构建多层可导航小世界图来实现高效搜索。该算法在Chroma中作为默认的向量索引实现，提供了良好的搜索精度和性能平衡。\n\n### HnswIndexProvider\n\n`HnswIndexProvider`是HNSW索引的生命周期管理器，负责索引的创建、打开、关闭和删除操作。\n\n```rust\n// 索引打开操作的核心签名\npub async fn open(\n &self,\n id: &IndexUuid,\n cache_key: &CollectionUuid,\n dimensionality: i32,\n distance_function: DistanceFunction,\n ef_search: usize,\n prefix_path: &str,\n) -> Result\n```\n\nSources: [rust/index/src/spann/types.rs:45-65](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### 关键配置参数\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| dimensionality | i32 | 向量维度 | 必填 |\n| distance_function | DistanceFunction | 距离函数 | 必填 |\n| ef_search | usize | 搜索时的候选集大小 | 可配置 |\n| prefix_path | &str | 存储路径前缀 | 必填 |\n\n### HnswIndexRef结构\n\n`HnswIndexRef`是对HNSW索引的引用类型，用于在查询阶段访问索引数据。它持有索引的所有权引用，确保索引在查询期间保持有效。\n\nSources: [rust/index/src/spann/types.rs:50](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## Spann稀疏向量索引\n\n### Spann架构\n\nSpann是Chroma专为稀疏向量设计的混合索引系统，结合了倒排索引和HNSW图的优点。它由三个核心组件构成：\n\n```mermaid\ngraph LR\n subgraph \"SpannIndex\"\n PostingList[Posting Lists]\n HNSWGraph[HNSW Graph]\n VersionsMap[Versions Map]\n end\n \n subgraph \"数据结构\"\n SpannPosting[SpannPosting
doc_offset_id
doc_embedding]\n SpannPostingList[SpannPostingList]\n end\n \n PostingList --> SpannPostingList\n HNSWGraph --> HnswIndexRef\n```\n\n### SpannPosting结构\n\n```rust\n#[derive(Debug)]\npub struct SpannPosting {\n pub doc_offset_id: u32, // 文档偏移ID\n pub doc_embedding: Vec, // 文档向量\n}\n```\n\nSources: [rust/index/src/spann/types.rs:38-42](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### SpannIndexReader\n\n`SpannIndexReader`提供对Spann索引的只读访问，包含以下核心字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| posting_lists | BlockfileReader | Posting列表读取器 |\n| hnsw_index | HnswIndexRef | HNSW图索引引用 |\n| versions_map | BlockfileReader | 版本映射 |\n| dimensionality | usize | 向量维度 |\n| adaptive_search_nprobe | bool | 自适应搜索开关 |\n| params | InternalSpannConfiguration | 内部配置参数 |\n\nSources: [rust/index/src/spann/types.rs:44-54](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### SpannIndexWriter\n\n`SpannIndexWriter`负责Spann索引的写入操作，核心创建方法签名：\n\n```rust\npub async fn from_id(\n hnsw_provider: &HnswIndexProvider,\n hnsw_id: Option<&IndexUuid>,\n versions_map_id: Option<&Uuid>,\n posting_list_id: Option<&Uuid>,\n max_head_id_bf_id: Option<&Uuid>,\n collection_id: &CollectionUuid,\n prefix_path: &str,\n dimensionality: usize,\n blockfile_provider: &BlockfileProvider,\n params: InternalSpannConfiguration,\n gc_context: GarbageCollectionContext,\n pl_block_size: usize,\n metrics: SpannMetrics,\n cmek: Option,\n) -> Result\n```\n\nSources: [rust/index/src/spann/types.rs:80-130](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### SpannPostingList管理\n\nSpann索引使用Blockfile来存储Posting List，支持高效的序列化和反序列化：\n\n```rust\npub async fn create_postings_list_writer(\n blockfile_provider: &BlockfileProvider,\n prefix_path: &str,\n pl_block_size: usize,\n cmek: Option,\n) -> Result\n```\n\n写入时支持配置最大块大小和CMEK（客户托管密钥）加密选项。\n\nSources: [rust/index/src/spann.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann.rs)\n\n## 量化模块（Quantization）\n\n### 量化概述\n\n量化模块提供了向量压缩功能，通过将高精度浮点向量转换为低精度的表示形式，显著减少存储空间和内存占用，同时尽可能保持搜索精度。\n\n### 量化配置\n\n| 配置项 | 说明 |\n|--------|------|\n| QuantizationType | 量化类型（PQR/SQ等） |\n| BucketCount | 量化桶数量 |\n| CodeWidth | 编码宽度 |\n| DistanceTable | 距离查表 |\n\nSources: [rust/index/src/quantization/mod.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/index/src/quantization/mod.rs)\n\n### 量化流程\n\n```mermaid\ngraph LR\n A[原始向量] --> B[训练量化器]\n B --> C[计算码本]\n C --> D[编码向量]\n D --> E[存储压缩向量]\n E --> F[查询时解码]\n F --> G[计算距离]\n```\n\n## 稀疏索引模块\n\n### 稀疏索引设计\n\n稀疏索引专门处理稀疏特征向量，典型应用于关键词匹配、推荐系统和混合搜索场景。\n\n### DirectoryBlock结构\n\n稀疏索引使用DirectoryBlock来组织posting blocks：\n\n```rust\npub struct DirectoryBlock(SparsePostingBlock);\n\nimpl DirectoryBlock {\n pub fn new(\n max_offsets: &[u32], // 每个posting block的最大偏移\n max_weights: &[f32], // 每个posting block的最大权重\n ) -> Result\n}\n```\n\nDirectoryBlock的二进制布局：\n- **Header**: magic bytes + block count + dimension-level max weight\n- **Body**: `[max_offset: u32 LE, max_weight: f32 LE] × num_entries`\n\nSources: [rust/types/src/sparse_posting_block.rs:1-60](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n\n### 稀疏索引错误处理\n\n| 错误类型 | 说明 |\n|---------|------|\n| MismatchedLengths | 偏移数组和权重数组长度不匹配 |\n| TooManyEntries | 条目数量超过u16::MAX限制 |\n\nSources: [rust/types/src/sparse_posting_block.rs:30-45](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n\n## Blockfile存储层\n\n### BlockfileProvider架构\n\nBlockfile是Chroma的底层存储抽象，封装了Arrow IPC格式的持久化存储。\n\n```mermaid\ngraph TD\n BlockfileProvider --> ArrowOrderedBlockfileWriter\n BlockfileProvider --> ArrowUnorderedBlockfileWriter\n BlockfileProvider --> BlockfileReader\n \n ArrowOrderedBlockfileWriter[\"ArrowOrderedBlockfileWriter
顺序写入\"]\n ArrowUnorderedBlockfileWriter[\"ArrowUnorderedBlockfileWriter
无序写入\"]\n \n BlockfileWriterOptions --> BlockfileProvider\n```\n\nSources: [rust/blockstore/src/arrow/provider.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n### 写入模式\n\n| 模式 | 说明 | 使用场景 |\n|------|------|---------|\n| Ordered | 顺序写入，保证追加顺序 | 日志、事务性数据 |\n| Unordered | 无序写入，批量优化 | 批量导入、重建索引 |\n\n### Fork操作\n\nBlockfile支持从现有blockfile创建分支（fork），用于创建索引快照或从检查点恢复：\n\n```rust\npub async fn fork(\n &self,\n fork_from: &Uuid,\n new_id: Uuid,\n prefix_path: &Path,\n max_block_size_bytes: usize,\n) -> Result>\n```\n\nSources: [rust/blockstore/src/arrow/provider.rs:30-60](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n### 块大小配置\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| max_block_size_bytes | 单个数据块的最大字节数 | BlockManager默认值 |\n\n## 距离函数\n\n系统支持多种距离函数，用于计算向量相似度：\n\n| 距离函数 | 说明 | 适用场景 |\n|---------|------|---------|\n| Cosine | 余弦距离 | 归一化向量 |\n| Dot | 点积 | 未归一化向量 |\n| L2 | 欧几里得距离 | 几何距离 |\n| IP | 内积 | 相似度排序 |\n\nSources: [rust/index/src/spann/types.rs:60](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## 错误处理\n\n### 索引错误类型\n\n| 错误类型 | 错误码 | 说明 |\n|---------|--------|------|\n| VersionsMapNotFound | NotFound | 版本映射不存在 |\n| ScanHnswError | Internal | HNSW扫描错误 |\n| DataInconsistencyError | Internal | 数据不一致 |\n| RngError | Internal | 随机数生成器错误 |\n\nSources: [rust/index/src/spann/types.rs:20-30](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## 索引生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: 创建索引\n Created --> Open: 打开索引\n Open --> Query: 执行查询\n Open --> Write: 写入数据\n Write --> Open: 写入完成\n Query --> Open: 查询完成\n Open --> Close: 关闭索引\n Close --> [*]: 资源释放\n Open --> Compact: 压缩合并\n Compact --> Open: 压缩完成\n```\n\n## 性能优化配置\n\n### HNSW搜索参数\n\n| 参数 | 说明 | 建议值 |\n|------|------|--------|\n| ef_search | 搜索时访问的最近邻候选数 | 100-500 |\n| ef_construction | 构建时使用的候选数 | 100-200 |\n| m | 每层连接数 | 16-64 |\n\n### 自适应搜索\n\nSpann索引支持`adaptive_search_nprobe`参数，启用时系统会根据查询结果动态调整搜索范围，在精度和性能之间自动平衡。\n\n## 总结\n\nChroma的向量索引系统通过模块化设计，提供了一套完整的高性能向量搜索解决方案：\n\n1. **HNSW模块**提供基础的ANN搜索能力\n2. **Spann模块**专门优化稀疏向量处理\n3. **量化模块**支持大规模数据的压缩存储\n4. **稀疏索引模块**处理高维稀疏特征\n5. **Blockfile存储层**确保数据持久化和高效读取\n\n这套系统在保证搜索精度的同时，通过多种优化策略实现了存储效率和查询性能的平衡，满足从原型开发到生产部署的各种场景需求。\n\n---\n\n\n\n## 查询执行引擎\n\n### Related Pages\n\nRelated topics: [向量索引系统](#page-vector-index), [Python客户端](#page-python-client)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/system/src/execution/operator.rs](https://github.com/chroma-core/chroma/blob/main/rust/system/src/execution/operator.rs)\n- [rust/types/src/execution/operator.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/execution/operator.rs)\n- [rust/worker/src/execution/operators/knn_hnsw.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/knn_hnsw.rs)\n- [rust/worker/src/execution/operators/filter.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/filter.rs)\n- [rust/execution/expression/plan.py](https://github.com/chroma-core/chroma/blob/main/rust/execution/expression/plan.py)\n \n\n# 查询执行引擎\n\n## 概述\n\nChroma 的查询执行引擎是系统的核心组件，负责处理向量搜索、元数据过滤和文档查询等操作。该引擎采用算子（Operator）模式设计，将复杂的查询流程分解为可组合的执行单元，支持灵活的查询规划和高效的结果处理。\n\n查询执行引擎的主要职责包括：\n\n- **向量最近邻搜索**：通过 HNSW 等索引实现高效的向量相似度搜索\n- **元数据过滤**：支持标量值和数组类型的元数据条件过滤\n- **文档全文搜索**：支持文档内容的包含和非包含查询\n- **结果聚合**：整合来自多个数据段的搜索结果\n\nSources: [rust/types/src/execution/operator.rs:1-50]()\n\n## 架构设计\n\n### 核心组件\n\n查询执行引擎由以下核心组件构成：\n\n| 组件 | 职责 | 位置 |\n|------|------|------|\n| 算子接口 (Operator Trait) | 定义算子的通用行为和错误处理 | rust/system/src/execution/operator.rs |\n| 类型定义 | 定义搜索结果、记录等数据结构 | rust/types/src/execution/operator.rs |\n| KNN 算子 | 实现基于 HNSW 的向量搜索 | rust/worker/src/execution/operators/knn_hnsw.rs |\n| 过滤算子 | 处理元数据和文档过滤条件 | rust/worker/src/execution/operators/filter.rs |\n| 执行计划 | Python 层的查询规划 | rust/execution/expression/plan.py |\n\n### 数据流架构\n\n```mermaid\ngraph TD\n A[查询请求] --> B[执行计划解析]\n B --> C[过滤算子 Filter]\n C --> D[KNN 算子 HNSW]\n D --> E[结果聚合]\n E --> F[SearchPayloadResult]\n F --> G[返回结果]\n \n C -.->|预过滤| H[元数据索引]\n D -.->|向量搜索| I[HNSW 索引]\n \n H --> J[Blockfile]\n I --> J\n```\n\nSources: [rust/execution/expression/plan.py:1-100]()\n\n## 算子接口设计\n\n### Operator Trait\n\n查询执行引擎中的所有算子都实现统一的 `Operator` 接口。该接口定义了算子的通用行为：\n\n```rust\n// 伪代码表示结构\npub trait Operator {\n type Error: ChromaError;\n \n async fn execute(&self, input: Input) -> Result;\n}\n```\n\n所有算子都需要实现 `ChromaError` trait，提供错误码映射和追踪配置：\n\n```rust\nimpl ChromaError for OperatorError {\n fn code(&self) -> ErrorCodes {\n match self {\n Self::Internal(_) => ErrorCodes::Internal,\n Self::InvalidArgument(_) => ErrorCodes::InvalidArgument,\n }\n }\n \n fn should_trace_error(&self) -> bool {\n true\n }\n}\n```\n\nSources: [rust/system/src/execution/operator.rs:1-80]()\n\n## 数据结构\n\n### 搜索结果类型\n\n查询执行引擎使用以下核心数据结构：\n\n#### SearchPayloadResult\n\n单次搜索的有效载荷结果：\n\n```rust\n#[derive(Clone, Debug, Default)]\npub struct SearchPayloadResult {\n pub records: Vec,\n}\n```\n\n包含搜索匹配的记录列表，每条记录包含向量、文档和元数据信息。\n\n#### SearchResult\n\n批量搜索操作的结果：\n\n```rust\n/// Results from a batch search operation.\n/// \n/// Contains results for each search payload in the batch, maintaining the same order\n/// as the input searches.\npub struct SearchResult {\n pub results: Vec,\n pub pulled_log_bytes: u64, // 内部指标：日志拉取字节数\n}\n```\n\nSources: [rust/types/src/execution/operator.rs:1-60]()\n\n### Where 过滤条件\n\n支持多种过滤条件的 `Where` 枚举类型：\n\n| 变体 | 描述 | 示例 |\n|------|------|------|\n| `Direct(value)` | 直接比较 | `id == \"xxx\"` |\n| `Key(metadata)` | 元数据字段比较 | `metadata.age > 21` |\n| `Document(expr)` | 文档内容匹配 | `contains(\"keyword\")` |\n| `And(left, right)` | 逻辑与 | `age > 18 AND active == true` |\n| `Or(left, right)` | 逻辑或 | `tag == \"A\" OR tag == \"B\"` |\n\n#### 文档操作符\n\n```rust\n#[derive(Clone, Debug, PartialEq)]\npub enum DocumentOperator {\n Contains, // 包含\n NotContains, // 不包含\n Regex, // 正则匹配\n NotRegex, // 正则不匹配\n}\n```\n\nSources: [rust/types/src/metadata.rs:1-50]()\n\n## 核心算子实现\n\n### KNN HNSW 算子\n\nKNN（K-Nearest Neighbors）算子使用 HNSW（Hierarchical Navigable Small World）算法实现高效的向量相似度搜索。\n\n#### 工作流程\n\n```mermaid\ngraph LR\n A[查询向量] --> B[HNSW 图遍历]\n B --> C[候选集合]\n C --> D[距离计算]\n D --> E[Top-K 结果]\n E --> F[结果包装]\n```\n\n#### 配置参数\n\n| 参数 | 类型 | 描述 | 默认值 |\n|------|------|------|--------|\n| `ef_search` | usize | 搜索时的动态列表大小 | 100 |\n| `k` | usize | 返回的最近邻数量 | 10 |\n| `distance_function` | DistanceFunction | 距离度量函数 | Cosine |\n| `dimensionality` | usize | 向量维度 | - |\n\n#### 关键方法\n\n```rust\nimpl<'me> SpannIndexReader<'me> {\n async fn hnsw_index_from_id(\n hnsw_provider: &HnswIndexProvider,\n id: &IndexUuid,\n cache_key: &CollectionUuid,\n distance_function: DistanceFunction,\n dimensionality: usize,\n ef_search: usize,\n prefix_path: &str,\n ) -> Result\n}\n```\n\nSources: [rust/worker/src/execution/operators/knn_hnsw.rs:1-80]()\n\n### 过滤算子\n\n过滤算子负责处理元数据和文档内容的条件过滤。\n\n#### 过滤类型\n\n| 过滤类型 | 处理对象 | 支持操作符 |\n|----------|----------|------------|\n| MetadataScalar | 标量元数据 | `=`, `!=`, `>`, `<`, `>=`, `<=`, `And`, `Or` |\n| MetadataArray | 数组元数据 | `contains_value`, `not_contains_value` |\n| Document | 文档全文 | `contains`, `not_contains`, `regex`, `not_regex` |\n\n#### Key 构建器\n\n`Key` 类型提供了流式 API 来构建过滤条件：\n\n```rust\n// 元数据标量过滤\nlet filter = Key::field(\"age\").gte(21);\nlet filter = Key::field(\"category\").eq(\"books\");\n\n// 元数据数组包含\nlet filter = Key::field(\"tags\").contains_value(\"action\");\n\n// 文档全文搜索\nlet filter = Key::Document.contains(\"machine learning\");\nlet filter = Key::Document.not_contains(\"deprecated\");\n```\n\nSources: [rust/worker/src/execution/operators/filter.rs:1-60]()\nSources: [rust/types/src/execution/operator.rs:80-150]()\n\n## 执行计划\n\n### Python 层规划\n\n在 Python 层，执行计划将用户查询转换为可执行的算子序列：\n\n```python\n# rust/execution/expression/plan.py\nclass ExecutionPlan:\n def __init__(self, collection):\n self.collection = collection\n self.operators = []\n \n def add_filter(self, where):\n # 添加过滤算子\n pass\n \n def add_knn(self, query_embedding, k):\n # 添加 KNN 搜索算子\n pass\n```\n\n### 查询转换流程\n\n```mermaid\ngraph TD\n A[Python API Query] --> B[WhereClause 解析]\n B --> C[ExecutionPlan 构建]\n C --> D[算子序列生成]\n D --> E[Rust 执行]\n E --> F[Protobuf 序列化]\n F --> G[结果返回]\n```\n\nSources: [rust/execution/expression/plan.py:1-100]()\n\n## 错误处理\n\n### 错误码映射\n\n| 错误类型 | ErrorCode | 说明 |\n|----------|-----------|------|\n| IOError | Internal | 输入输出错误 |\n| ArrowError | Internal | Arrow 格式错误 |\n| ArrowLayoutVerificationError | Internal | Arrow 布局验证失败 |\n| NoRecordBatches | Internal | IPC 文件无记录批次 |\n| BlockToBytesError | Internal | 块序列化错误 |\n| CacheError | Internal | 缓存操作错误 |\n\n### 错误处理实现\n\n```rust\nimpl ChromaError for BlockLoadError {\n fn code(&self) -> ErrorCodes {\n match self {\n BlockLoadError::IOError(_) => ErrorCodes::Internal,\n BlockLoadError::ArrowError(_) => ErrorCodes::Internal,\n BlockLoadError::ArrowLayoutVerificationError(_) => ErrorCodes::Internal,\n BlockLoadError::NoRecordBatches => ErrorCodes::Internal,\n BlockLoadError::BlockToBytesError(_) => ErrorCodes::Internal,\n BlockLoadError::CacheError(_) => ErrorCodes::Internal,\n }\n }\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:1-50]()\n\n## 性能优化\n\n### 索引结构\n\nChroma 使用多级索引结构优化查询性能：\n\n1. **Blockfile**：底层存储，支持高效的块读写\n2. **HNSW 索引**：向量搜索的核心，提供对数级搜索复杂度\n3. **Sparse Index**：稀疏向量索引，用于高效的范围查询\n\n### 执行策略\n\n| 策略 | 适用场景 | 优势 |\n|------|----------|------|\n| 预过滤 | 过滤条件较严格 | 减少搜索空间 |\n| 后过滤 | 过滤条件较宽松 | 提高搜索并行度 |\n| 混合过滤 | 复杂查询 | 平衡精度和性能 |\n\n### 缓存机制\n\n执行引擎利用多层缓存提升性能：\n\n- **HNSW 索引缓存**：避免重复加载索引\n- **块缓存**：减少磁盘 IO\n- **查询结果缓存**：加速重复查询\n\n## 扩展性\n\n### 自定义算子\n\n系统支持通过实现 `Operator` trait 添加自定义算子：\n\n```rust\npub trait Operator {\n type Error: ChromaError;\n \n async fn execute(&self, input: Input) -> Result;\n}\n```\n\n### 算子组合\n\n通过算子的可组合性，可以构建复杂的查询管道：\n\n```mermaid\ngraph LR\n A[Query] --> B[Filter1]\n B --> C[Filter2]\n C --> D[KNNSearch]\n D --> E[Rank]\n E --> F[Project]\n F --> G[Result]\n```\n\n## 总结\n\nChroma 的查询执行引擎通过算子模式和分层架构，实现了高效、灵活的查询处理能力。核心设计特点包括：\n\n- **统一的算子接口**：简化了算子的实现和组合\n- **多级索引支持**：HNSW + Blockfile 提供高效的向量和标量查询\n- **灵活的结果聚合**：支持批量搜索和结果合并\n- **完善的错误处理**：提供细粒度的错误码和追踪机制\n\n这一架构使得 Chroma 能够高效处理大规模向量数据和复杂的查询条件，同时保持良好的可扩展性。\n\n---\n\n\n\n## Python客户端\n\n### Related Pages\n\nRelated topics: [JavaScript/TypeScript客户端](#page-javascript-client), [嵌入函数集成](#page-embedding-functions)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [chromadb/api/client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/client.py)\n- [chromadb/api/async_client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/async_client.py)\n- [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)\n- [chromadb/api/models/AsyncCollection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/AsyncCollection.py)\n- [chromadb/api/fastapi.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/fastapi.py)\n \n\n# Python客户端\n\n## 概述\n\nChroma的Python客户端是官方提供的Python SDK，为开发者提供了与Chroma向量数据库交互的完整接口。该客户端支持两种运行模式：嵌入式模式（Embedded Mode）和客户端-服务器模式（Client-Server Mode），满足不同场景下的使用需求。\n\nPython客户端的核心API仅包含四个主要函数，通过简洁的接口封装了文档管理、向量嵌入、相似度搜索等核心功能。Sources: [README.md]()\n\n## 架构设计\n\n### 整体架构\n\nChroma Python客户端采用分层架构设计，主要包含以下核心组件：\n\n```mermaid\ngraph TD\n A[Python Client] --> B[Sync Client]\n A --> C[Async Client]\n B --> D[Collection]\n C --> E[AsyncCollection]\n D --> F[Embedding Functions]\n E --> F\n B --> G[FastAPI Client]\n C --> G\n G --> H[Chroma Server]\n```\n\n### 客户端类型\n\n| 客户端类型 | 文件位置 | 用途 | 适用场景 |\n|-----------|---------|------|---------|\n| `Client` | `chromadb/api/client.py` | 同步客户端 | 标准Python应用 |\n| `AsyncClient` | `chromadb/api/async_client.py` | 异步客户端 | 异步Web框架、高并发应用 |\n| `FastAPI` | `chromadb/api/fastapi.py` | 服务器端API | Chroma服务器部署 |\n\nSources: [chromadb/api/client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/client.py), [chromadb/api/async_client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/async_client.py), [chromadb/api/fastapi.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/fastapi.py)()\n\n## 同步客户端\n\n### 初始化与配置\n\n同步客户端通过`chromadb.Client()`方法创建，支持嵌入式内存模式和持久化存储模式。\n\n```python\nimport chromadb\n\n# 嵌入式内存模式（临时数据）\nclient = chromadb.Client()\n\n# 带持久化的嵌入式模式\nclient = chromadb.PersistentClient(path=\"/path/to/chroma_db\")\n```\n\n### 核心功能\n\n**Collection管理**\n\nCollection是Chroma中组织文档和向量数据的基本单元。客户端提供了完整的Collection操作接口：\n\n```python\n# 创建Collection\ncollection = client.create_collection(\n name=\"my-documents\",\n metadata={\"description\": \"文档集合\"}\n)\n\n# 获取已存在的Collection\ncollection = client.get_collection(name=\"my-documents\")\n\n# 获取或创建Collection\ncollection = client.get_or_create_collection(name=\"my-documents\")\n\n# 列出所有Collection\ncollections = client.list_collections()\n\n# 删除Collection\nclient.delete_collection(name=\"my-documents\")\n```\n\nSources: [chromadb/api/client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/client.py), [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)()\n\n## 异步客户端\n\n### 异步支持\n\n`AsyncClient`提供了完全异步的操作接口，适用于`asyncio`环境和异步Web框架（如FastAPI）。\n\n```python\nimport chromadb\n\n# 创建异步客户端\nclient = chromadb.AsyncClient()\n\n# 异步创建Collection\ncollection = await client.create_collection(name=\"async-collection\")\n```\n\n### 性能优势\n\n| 特性 | 同步客户端 | 异步客户端 |\n|-----|-----------|-----------|\n| 并发处理 | 单线程阻塞 | 多任务并发 |\n| 适用框架 | Django, Flask | FastAPI, aiohttp |\n| 连接复用 | 每次请求新建 | 长连接复用 |\n| 内存占用 | 较低 | 略高 |\n\nSources: [chromadb/api/async_client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/async_client.py), [chromadb/api/models/AsyncCollection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/AsyncCollection.py)()\n\n## Collection操作\n\n### 数据模型\n\nCollection支持存储以下类型的数据：\n\n```python\ncollection.add(\n documents=[\"文档内容1\", \"文档内容2\"], # 文档文本\n metadatas=[{\"source\": \"doc1\"}, {\"source\": \"doc2\"}], # 元数据\n ids=[\"id1\", \"id2\"], # 唯一标识符\n embeddings=[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] # 可选：自定义向量\n)\n```\n\n### 插入操作\n\n| 参数 | 类型 | 必需 | 说明 |\n|-----|------|-----|------|\n| `ids` | List[str] | 是 | 文档唯一标识符 |\n| `documents` | List[str] | 否 | 文档内容文本 |\n| `embeddings` | List[List[float]] | 否 | 向量嵌入 |\n| `metadatas` | List[dict] | 否 | 元数据字典 |\n\nSources: [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)()\n\n### 查询操作\n\n```python\n# 基于文本的相似度查询\nresults = collection.query(\n query_texts=[\"查询文本\"],\n n_results=2, # 返回2个最相似结果\n where={\"source\": \"doc1\"}, # 元数据过滤\n where_document={\"$contains\": \"关键词\"} # 文档内容过滤\n)\n\n# 基于向量的查询\nresults = collection.query(\n query_embeddings=[[1.0, 2.0, 3.0]],\n n_results=2\n)\n```\n\n### 条件过滤\n\nChroma支持强大的条件过滤功能：\n\n```python\n# 元数据过滤\ncollection.query(\n query_texts=[\"查询\"],\n where={\"metadata_field\": \"value\"}\n)\n\n# 文档内容过滤\ncollection.query(\n query_texts=[\"查询\"],\n where_document={\"$contains\": \"搜索字符串\"}\n)\n```\n\nSources: [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)()\n\n## Embedding函数\n\n### 嵌入函数架构\n\n```mermaid\ngraph LR\n A[Input Text] --> B[Embedding Function]\n B --> C[Vector Embedding]\n C --> D[Storage/Indexing]\n```\n\n### 内置嵌入函数\n\nChroma Python客户端支持多种嵌入函数提供商：\n\n| 提供商 | 包名 | 默认模型 |\n|-------|------|---------|\n| OpenAI | `chromadb.utils.embedding_functions` | text-embedding-ada-002 |\n| Cohere | `chromadb.utils.embedding_functions` | embed-english-v3.0 |\n| Hugging Face | `chromadb.utils.embedding_functions` | sentence-transformers |\n| Ollama | `chromadb.utils.embedding_functions` | 自定义模型 |\n\n### 自定义嵌入函数\n\n```python\nfrom chromadb.utils.embedding_functions import OpenAIEmbeddingFunction\n\nembedder = OpenAIEmbeddingFunction(\n api_key=\"your-api-key\",\n model_name=\"text-embedding-3-small\"\n)\n\ncollection = client.create_collection(\n name=\"my-collection\",\n embedding_function=embedder\n)\n```\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)()\n\n## 使用模式\n\n### 嵌入式模式\n\n适用于本地开发和测试，数据存储在内存或本地文件系统：\n\n```python\nimport chromadb\n\n# 内存模式\nclient = chromadb.Client()\n\n# 本地持久化模式\nclient = chromadb.PersistentClient(path=\"./chroma_db\")\n```\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)()\n\n### 客户端-服务器模式\n\n适用于生产环境和分布式部署：\n\n```bash\n# 启动Chroma服务器\nchroma run --path /chroma_db_path --host 0.0.0.0 --port 8000\n```\n\n```python\nimport chromadb\n\n# 连接远程服务器\nclient = chromadb.Client(\n settings=Settings(\n chroma_api_impl=\"rest\",\n persist_directory=\"http://localhost:8000\"\n )\n)\n```\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)()\n\n## API参考\n\n### 客户端方法\n\n#### `chromadb.Client()`\n\n创建Chroma客户端实例。\n\n#### `client.create_collection(name, metadata, embedding_function)`\n\n创建新的Collection。\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| `name` | str | Collection名称 |\n| `metadata` | dict | Collection元数据 |\n| `embedding_function` | function | 嵌入函数 |\n\n#### `client.get_collection(name)`\n\n获取指定名称的Collection。\n\n#### `client.list_collections()`\n\n返回所有Collection列表。\n\n#### `client.delete_collection(name)`\n\n删除指定Collection。\n\n### Collection方法\n\n| 方法 | 说明 |\n|-----|------|\n| `add()` | 添加文档 |\n| `get()` | 获取文档 |\n| `update()` | 更新文档 |\n| `upsert()` | 插入或更新 |\n| `delete()` | 删除文档 |\n| `query()` | 相似度查询 |\n| `peek()` | 查看前N条记录 |\n| `count()` | 统计文档数量 |\n| `modify()` | 修改Collection元数据 |\n\nSources: [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)()\n\n## 最佳实践\n\n### 性能优化\n\n1. **批量操作**：尽量使用批量添加而非单条添加\n2. **嵌入函数复用**：创建Collection时指定嵌入函数，避免重复初始化\n3. **索引优化**：合理设置`hnsw:space`参数选择合适的距离度量\n\n### 数据组织\n\n1. **合理的Collection划分**：按主题或数据类型分离Collection\n2. **元数据设计**：元数据用于过滤，应设计清晰的元数据结构\n3. **ID管理**：使用有意义的ID便于数据追踪\n\n### 错误处理\n\n```python\ntry:\n collection = client.get_collection(name=\"non-existent\")\nexcept Exception as e:\n print(f\"Error: {e}\")\n```\n\n## 总结\n\nChroma Python客户端提供了简洁而强大的接口来管理向量数据。通过同步和异步两种客户端类型，配合灵活的Collection管理和丰富的嵌入函数支持，开发者可以快速构建基于向量检索的AI应用。Sources: [chromadb/api/client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/client.py), [chromadb/api/async_client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/async_client.py), [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py), [chromadb/api/models/AsyncCollection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/AsyncCollection.py), [chromadb/api/fastapi.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/fastapi.py)()\n\n---\n\n\n\n## JavaScript/TypeScript客户端\n\n### Related Pages\n\nRelated topics: [Python客户端](#page-python-client)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [clients/js/packages/chromadb-core/src/ChromaClient.ts](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-core/src/ChromaClient.ts)\n- [clients/new-js/packages/chromadb/src/chroma-client.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/src/chroma-client.ts)\n- [clients/new-js/packages/chromadb/src/api/client.gen.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/src/api/client.gen.ts)\n- [clients/js/packages/chromadb-client/src/index.ts](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-client/src/index.ts)\n- [clients/new-js/packages/chromadb/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/package.json)\n- [clients/js/packages/chromadb/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb/package.json)\n- [clients/js/packages/chromadb-client/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-client/package.json)\n- [clients/js/packages/chromadb-core/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-core/package.json)\n- [clients/new-js/packages/ai-embeddings/all/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/all/package.json)\n- [clients/new-js/packages/ai-embeddings/common/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/common/package.json)\n \n\n# JavaScript/TypeScript客户端\n\nChromaDB JavaScript/TypeScript客户端是Chroma向量数据库的官方前端SDK，支持Node.js环境和现代浏览器。该客户端提供了与Chroma服务器端进行通信的完整接口，包括集合管理、向量存储、相似性查询等功能。\n\n## 架构概述\n\nChromaDB JavaScript客户端存在两套主要实现，分别位于不同的代码目录中：\n\n### 客户端版本对比\n\n| 特性 | 新版客户端 (`new-js`) | 旧版客户端 (`js`) |\n|------|---------------------|------------------|\n| 版本号 | 3.4.5 | 2.4.7 |\n| 模块格式 | ESM优先，支持CJS | 同时支持ESM和CJS |\n| 嵌入函数 | 通过独立包提供 | 内置或作为peerDependencies |\n| 构建工具 | tsup | tsup |\n| API风格 | 现代化Promise/Async | 兼容旧版 |\n\n### 代码结构\n\n```mermaid\ngraph TD\n subgraph \"clients/new-js\"\n A[new-js/chromadb] --> B[new-js/ai-embeddings]\n B --> C[各嵌入提供者包]\n C --> D[TogetherAI]\n C --> E[GoogleGemini]\n C --> F[Jina]\n C --> G[VoyageAI]\n C --> H[SentenceTransformer]\n C --> I[BM25]\n end\n \n subgraph \"clients/js\"\n J[chromadb-core] --> K[chromadb-embedded]\n J --> L[chromadb-client]\n end\n \n M[Chroma Server] <--> N[HTTP API]\n A --> N\n J --> N\n K --> M\n```\n\n## 核心组件\n\n### 1. ChromaClient (新版)\n\n新版客户端的核心类位于 `clients/new-js/packages/chromadb/src/chroma-client.ts`，提供了与Chroma服务器通信的主要接口。\n\n**主要功能：**\n\n- 创建和管理集合\n- 执行向量查询操作\n- 管理集合元数据\n- 处理身份验证（可选）\n\n**基本用法：**\n\n```typescript\nimport { ChromaClient } from 'chromadb';\n\nconst client = new ChromaClient({\n path: 'http://localhost:8000',\n});\n\nconst collection = await client.createCollection({\n name: 'my-collection',\n embeddingFunction: embedder, // 可选自定义嵌入函数\n metadata: { 'description': '我的第一个集合' }\n});\n```\n\nSources: [clients/new-js/packages/chromadb/src/chroma-client.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/src/chroma-client.ts)\n\n### 2. ChromaClient (旧版)\n\n旧版客户端位于 `clients/js/packages/chromadb-core/src/ChromaClient.ts`，功能类似但API略有不同。\n\n**包结构对比：**\n\n| 包名 | 说明 | 嵌入函数 |\n|------|------|---------|\n| `chromadb` | 完整包，内置所有嵌入库 | 已包含 |\n| `chromadb-client` | 仅客户端，嵌入为peerDependencies | 需单独安装 |\n\nSources: [clients/js/packages/chromadb-core/src/ChromaClient.ts](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-core/src/ChromaClient.ts)\n\n### 3. Collection操作\n\n集合是Chroma中组织向量数据的基本单位。以下是Collection的主要操作：\n\n```typescript\n// 添加文档\nawait collection.add({\n ids: ['1', '2', '3'],\n documents: ['第一个文档', '第二个文档', '第三个文档'],\n metadatas: [{ source: 'a' }, { source: 'b' }, { source: 'c' }],\n});\n\n// 查询相似文档\nconst results = await collection.query({\n queryTexts: ['查询文本'],\n nResults: 2,\n});\n\n// 获取数据\nconst data = await collection.get({\n ids: ['1', '2'],\n where: { source: 'a' },\n});\n\n// 删除数据\nawait collection.delete({\n where: { source: 'b' },\n});\n```\n\n## 嵌入函数系统\n\nChroma使用嵌入函数(Embedding Function)将文本转换为向量。新版客户端通过独立包提供各种嵌入提供者。\n\n### 支持的嵌入提供者\n\n| 提供者 | 包名 | 模型默认 |\n|--------|------|---------|\n| Together AI | `@chroma-core/together-ai` | togethercomputer/m2-bert-80M-8k-retrieval |\n| Google Gemini | `@chroma-core/google-gemini` | text-embedding-004 |\n| Jina AI | `@chroma-core/jina` | jina-embeddings-v2-base-en |\n| Voyage AI | `@chroma-core/voyageai` | voyage-2 |\n| HuggingFace | `@chroma-core/huggingface-server` | - |\n| Cohere | `@chroma-core/cohere` | - |\n| Sentence Transformer | `@chroma-core/sentence-transformer` | - |\n| BM25 (稀疏) | `@chroma-core/chroma-bm25` | - |\n\nSources: [clients/new-js/packages/ai-embeddings/all/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/all/package.json)\n\n### 嵌入函数配置示例\n\n```typescript\nimport { ChromaClient } from 'chromadb';\nimport { JinaEmbeddingFunction } from '@chroma-core/jina';\n\n// 初始化Jina嵌入函数\nconst embedder = new JinaEmbeddingFunction({\n apiKey: process.env.JINA_API_KEY,\n modelName: 'jina-embeddings-v2-base-en',\n dimensions: 768,\n normalized: true,\n});\n\n// 创建客户端并指定嵌入函数\nconst client = new ChromaClient({ path: 'http://localhost:8000' });\nconst collection = await client.createCollection({\n name: 'my-collection',\n embeddingFunction: embedder,\n});\n```\n\n### 通用工具包\n\n`@chroma-core/ai-embeddings-common` 包提供了所有嵌入提供者共享的通用工具：\n\n- API请求封装\n- 响应格式标准化\n- 配置验证\n- AJV JSON Schema验证\n\nSources: [clients/new-js/packages/ai-embeddings/common/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/common/package.json)\n\n## API客户端生成\n\n新版客户端使用OpenAPI规范生成类型安全的API客户端：\n\n```mermaid\ngraph LR\n A[OpenAPI Spec] --> B[openapi-generator-plus]\n B --> C[client.gen.ts]\n C --> D[类型定义]\n C --> E[API方法]\n```\n\n生成的API文件位于 `clients/new-js/packages/chromadb/src/api/client.gen.ts`，包含：\n\n- 完整的TypeScript类型定义\n- 请求/响应模型\n- HTTP客户端封装\n\nSources: [clients/new-js/packages/chromadb/src/api/client.gen.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/src/api/client.gen.ts)\n\n## 包配置与导出\n\n### 模块导出配置\n\n新版客户端使用现代化的导出配置，支持ESM和CommonJS：\n\n```json\n{\n \"exports\": {\n \".\": {\n \"import\": {\n \"types\": \"./dist/chromadb.d.ts\",\n \"default\": \"./dist/chromadb.mjs\"\n },\n \"require\": {\n \"types\": \"./dist/cjs/chromadb.d.cts\",\n \"default\": \"./dist/cjs/chromadb.cjs\"\n }\n }\n }\n}\n```\n\nSources: [clients/new-js/packages/chromadb/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/package.json)\n\n### 兼容性矩阵\n\n| Node.js版本 | 支持情况 |\n|-------------|---------|\n| >= 20 | 完整支持 (new-js) |\n| >= 14.17.0 | 基础支持 (旧版js) |\n| >= 10 | 原生 bindings |\n\n## 开发与构建\n\n### 构建命令\n\n```bash\n# 新版客户端构建\ncd clients/new-js/packages/chromadb\npnpm build\n\n# 旧版客户端构建\ncd clients/js\npnpm build:core\npnpm build:packages\n\n# 安装依赖\npnpm install\n\n# 运行测试\npnpm test\n```\n\n### 发布流程\n\n```bash\n# 发布正式版本\npnpm release\n\n# 发布Alpha版本\npnpm release_alpha\n\n# 发布开发版本\npnpm release_dev\n```\n\nSources: [clients/js/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/package.json)\n\n## 使用示例\n\n### Node.js环境完整示例\n\n```typescript\nimport { ChromaClient } from 'chromadb';\nimport { JinaEmbeddingFunction } from '@chroma-core/jina';\n\n// 1. 初始化嵌入函数\nconst embedder = new JinaEmbeddingFunction({\n apiKey: process.env.JINA_API_KEY,\n});\n\n// 2. 创建客户端\nconst client = new ChromaClient({\n path: 'http://localhost:8000',\n});\n\n// 3. 创建或获取集合\nconst collection = await client.getOrCreateCollection({\n name: 'documents',\n embeddingFunction: embedder,\n});\n\n// 4. 添加文档\nawait collection.add({\n ids: ['doc1', 'doc2', 'doc3'],\n documents: [\n '机器学习是人工智能的一个分支',\n '深度学习使用神经网络模型',\n '自然语言处理研究人机交互'\n ],\n metadatas: [\n { category: 'ai', year: 2024 },\n { category: 'ml', year: 2024 },\n { category: 'nlp', year: 2024 }\n ]\n});\n\n// 5. 查询相似文档\nconst results = await collection.query({\n queryTexts: ['什么是深度学习？'],\n nResults: 2,\n});\n\nconsole.log('相似文档:', results.documents);\nconsole.log('距离:', results.distances);\n```\n\n### 旧版客户端用法\n\n```typescript\nimport { ChromaClient } from 'chromadb';\n\n// 使用默认配置连接\nconst client = new ChromaClient();\nconst collection = await client.createCollection('test');\n\n// 使用自定义服务器地址\nconst remoteClient = new ChromaClient({\n path: 'https://your-chroma-server.com'\n});\n```\n\nSources: [clients/js/packages/chromadb-client/src/index.ts](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-client/src/index.ts)\n\n## 依赖管理\n\n### 核心依赖\n\n| 依赖包 | 用途 |\n|--------|------|\n| isomorphic-fetch | 跨平台HTTP请求 |\n| ajv | JSON Schema验证 |\n| cliui | 命令行界面 |\n\n### 嵌入函数peerDependencies (旧版客户端)\n\n```json\n{\n \"peerDependencies\": {\n \"@google/generative-ai\": \"^0.1.1\",\n \"@xenova/transformers\": \"^2.17.2\",\n \"chromadb-default-embed\": \"^2.14.0\",\n \"cohere-ai\": \"^7.0.0\"\n }\n}\n```\n\nSources: [clients/js/packages/chromadb/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb/package.json)\n\n## 测试策略\n\n### 测试命令\n\n```bash\n# 运行所有测试\npnpm test\n\n# 运行功能测试（排除认证测试）\npnpm test:functional\n\n# 更新快照测试\npnpm test:update\n```\n\n### 测试环境要求\n\n- Node.js >= 14.17.0\n- Chroma服务器运行于 localhost:8000\n- 可选的认证配置用于auth测试\n\n## 技术选型说明\n\n### 为什么使用tsup\n\ntsup是Chroma JS客户端选用的构建工具，原因如下：\n\n- **零配置**: 自动处理TypeScript和Babel\n- **多格式输出**: 同时生成ESM、CJS、类型定义\n- **性能**: 基于esbuild，构建速度极快\n- **Source Maps**: 支持调试\n\n### 为什么分离嵌入包\n\n新版客户端将嵌入函数分离为独立包的好处：\n\n1. **减少主包体积**: 用户只需安装需要的嵌入提供者\n2. **独立版本管理**: 各嵌入提供者可独立更新\n3. **Tree-shaking**: 构建时可移除未使用的嵌入代码\n4. **灵活性**: 支持自定义嵌入函数实现\n\n## 相关资源\n\n- [官方文档](https://docs.trychroma.com/)\n- [GitHub仓库](https://github.com/chroma-core/chroma)\n- [API参考](./api-reference.md)\n- [嵌入函数指南](./embedding-functions.md)\n\n---\n\n\n\n## 嵌入函数集成\n\n### Related Pages\n\nRelated topics: [Python客户端](#page-python-client), [JavaScript/TypeScript客户端](#page-javascript-client)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [clients/new-js/packages/ai-embeddings/common/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/common/README.md)\n- [clients/new-js/packages/ai-embeddings/all/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/all/README.md)\n- [clients/new-js/packages/ai-embeddings/jina/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/jina/README.md)\n- [clients/new-js/packages/ai-embeddings/morph/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/morph/README.md)\n- [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chroma-cloud-qwen/README.md)\n- [clients/new-js/src/embedding-function.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/src/embedding-function.ts)\n- [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)\n- [schemas/embedding_functions/README.md](https://github.com/chroma-core/chroma/blob/main/schemas/embedding_functions/README.md)\n- [rust/types/src/api_types.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/api_types.rs)\n \n\n# 嵌入函数集成\n\n## 概述\n\n嵌入函数集成是 ChromaDB 中用于将文本、文档或其他数据转换为向量表示的核心机制。ChromaDB 支持多种嵌入提供商的集成，包括 OpenAI、Cohere、Jina、HuggingFace 等云服务，以及本地模型如 Ollama 和 HuggingFace Server。\n\nChromaDB 的嵌入函数设计遵循跨语言兼容性原则，确保 Python 客户端和 JavaScript/TypeScript 客户端能够共享相同的配置模式和验证机制。Sources: [clients/new-js/packages/ai-embeddings/common/README.md]()\n\n## 架构设计\n\n### 整体架构\n\nChromaDB 采用模块化设计，将嵌入函数抽象为可插拔的接口。核心组件包括：\n\n```mermaid\ngraph TD\n A[ChromaDB Client] --> B[Embedding Function Abstraction]\n B --> C[Provider-Specific Implementations]\n C --> D[OpenAI]\n C --> E[Cohere]\n C --> F[Jina]\n C --> G[HuggingFace]\n C --> H[Ollama]\n C --> I[Morph]\n C --> J[Google Gemini]\n C --> K[Voyage AI]\n C --> L[Cloudflare Worker AI]\n \n M[Schema Validation] --> B\n M --> N[base_schema.json]\n M --> O[Provider Schemas]\n```\n\n### 嵌入函数配置流程\n\n嵌入函数在客户端层面进行实例化和配置，然后与集合（Collection）绑定使用：\n\n```mermaid\ngraph LR\n A1[用户代码] --> B1[创建嵌入函数实例]\n B1 --> C1[配置参数验证]\n C1 --> D1[Schema 验证]\n D1 --> E1[与 Collection 绑定]\n E1 --> F1[数据添加时自动嵌入]\n F1 --> G1[查询时自动嵌入查询文本]\n```\n\n## 嵌入函数包结构\n\n### JavaScript/TypeScript 包组织\n\nChromaDB 的 JavaScript 客户端将不同嵌入提供商拆分为独立包，便于按需安装：\n\n| 包名 | 用途 | 源码路径 |\n|------|------|----------|\n| `@chroma-core/ai-embeddings-common` | 通用工具函数 | clients/new-js/packages/ai-embeddings/common/ |\n| `@chroma-core/all` | 所有嵌入提供商的聚合包 | clients/new-js/packages/ai-embeddings/all/ |\n| `@chroma-core/jina` | Jina AI 嵌入 | clients/new-js/packages/ai-embeddings/jina/ |\n| `@chroma-core/morph` | Morph 嵌入 | clients/new-js/packages/ai-embeddings/morph/ |\n| `@chroma-core/chroma-cloud-qwen` | Qwen 云端嵌入 | clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/ |\n\nSources: [clients/new-js/packages/ai-embeddings/all/README.md](), [clients/new-js/packages/ai-embeddings/common/README.md]()\n\n### 通用工具函数\n\n`@chroma-core/ai-embeddings-common` 包提供以下核心功能：\n\n```typescript\n// 导入示例\nimport { validateConfigSchema, snakeCase, isBrowser } from '@chroma-core/ai-embeddings-common';\n\n// 驼峰式转蛇式命名（用于 API 兼容性）\nconst snakeCaseConfig = snakeCase({ modelName: 'text-embedding-3-small' });\n// 结果: { model_name: 'text-embedding-3-small' }\n\n// 检测浏览器环境\nif (isBrowser()) {\n // 浏览器特定逻辑\n}\n\n// 验证嵌入函数配置\nvalidateConfigSchema(config, 'openai');\n```\n\n核心功能包括：\n\n- **Schema 验证**：使用 JSON Schema Draft-07 规范验证嵌入函数配置\n- **命名转换**：将 camelCase JavaScript 对象转换为 snake_case 以匹配 API 规范\n- **环境检测**：识别浏览器与 Node.js 运行环境的差异\n\nSources: [clients/new-js/packages/ai-embeddings/common/README.md]()\n\n## Schema 验证系统\n\n### 跨语言兼容性\n\nChromaDB 在 `schemas/embedding_functions/` 目录维护统一的 JSON Schema 定义，确保 Python 和 JavaScript 客户端的配置保持一致：\n\n```mermaid\ngraph TD\n A[Schema Definition] --> B[Python Client]\n A --> C[JavaScript Client]\n B --> D[validate_config function]\n C --> E[validateConfig function]\n```\n\n### Schema 结构\n\n每个嵌入函数 schema 遵循 JSON Schema Draft-07 规范：\n\n| 字段 | 说明 |\n|------|------|\n| `version` | Schema 版本号 |\n| `title` | Schema 标题 |\n| `description` | 功能描述 |\n| `properties` | 可配置属性 |\n| `required` | 必需属性 |\n| `additionalProperties` | 是否允许额外属性（始终为 false） |\n\n### Python 端验证\n\n```python\nfrom chromadb.utils.embedding_functions.schemas import validate_config\n\n# 验证配置\nconfig = {\n \"api_key_env_var\": \"CHROMA_OPENAI_API_KEY\",\n \"model_name\": \"text-embedding-ada-002\"\n}\nvalidate_config(config, \"openai\")\n```\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](), [schemas/embedding_functions/README.md]()\n\n## API 类型定义\n\n### Include 枚举\n\n在 Rust 实现中，嵌入函数的返回内容通过 `Include` 枚举控制：\n\n```rust\n#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]\n#[cfg_attr(feature = \"utoipa\", derive(utoipa::ToSchema))]\npub enum Include {\n Distance,\n Document,\n Embedding,\n Metadata,\n Uri,\n}\n```\n\n### IncludeList 默认值\n\n| 方法 | 默认包含字段 |\n|------|-------------|\n| `default_query()` | Document, Metadata, Distance |\n| `default_get()` | Document, Metadata |\n| `all()` | Document, Metadata, Distance, Embedding, Uri |\n\nSources: [rust/types/src/api_types.rs]()\n\n## 嵌入函数实现示例\n\n### Jina 嵌入函数\n\nJina AI 嵌入函数是 ChromaDB 支持的重要嵌入提供商之一：\n\n```typescript\nimport { ChromaClient } from 'chromadb';\nimport { JinaEmbeddingFunction } from '@chroma-core/jina';\n\n// 初始化嵌入函数\nconst embedder = new JinaEmbeddingFunction({\n apiKey: 'your-api-key', // 或设置 JINA_API_KEY 环境变量\n modelName: 'jina-embeddings-v2-base-en',\n task: 'retrieval.passage',\n dimensions: 768,\n lateChunking: false,\n truncate: true,\n normalized: true,\n embeddingType: 'float'\n});\n\n// 创建客户端和集合\nconst client = new ChromaClient({ path: 'http://localhost:8000' });\nconst collection = await client.createCollection({\n name: 'my-collection',\n embeddingFunction: embedder,\n});\n\n// 添加文档（自动嵌入）\nawait collection.add({\n ids: [\"1\", \"2\", \"3\"],\n documents: [\"Document 1\", \"Document 2\", \"Document 3\"],\n});\n\n// 查询（自动嵌入查询文本）\nconst results = await collection.query({\n queryTexts: [\"Sample query\"],\n nResults: 2,\n});\n```\n\n**配置选项**：\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `apiKey` | string | JINA_API_KEY env | API 密钥 |\n| `modelName` | string | jina-embeddings-v2-base-en | 模型名称 |\n| `task` | string | retrieval.passage | 任务类型 |\n| `dimensions` | number | 768 | 向量维度 |\n| `lateChunking` | boolean | false | 延迟分块 |\n| `truncate` | boolean | true | 截断超长文本 |\n| `normalized` | boolean | true | L2 归一化 |\n| `embeddingType` | string | float | 嵌入类型 |\n\nSources: [clients/new-js/packages/ai-embeddings/jina/README.md]()\n\n### Morph 嵌入函数\n\n```typescript\nimport { MorphEmbeddingFunction } from '@chroma-core/morph';\n\nconst morphEmbedding = new MorphEmbeddingFunction({\n api_key: 'your-morph-api-key',\n model_name: 'morph-embedding-v2', // 默认值\n api_base: 'https://api.morphllm.com/v1', // 默认值\n encoding_format: 'float' // 默认值\n});\n```\n\n**配置参数**：\n\n| 参数 | 必需 | 默认值 | 说明 |\n|------|------|--------|------|\n| `api_key` | 否 | 环境变量 | API 密钥 |\n| `model_name` | 否 | morph-embedding-v2 | 模型名称 |\n| `api_base` | 否 | https://api.morphllm.com/v1 | API 基础 URL |\n| `encoding_format` | 否 | float | 编码格式 (float 或 base64) |\n\nSources: [clients/new-js/packages/ai-embeddings/morph/README.md]()\n\n### Qwen 云端嵌入函数\n\n```typescript\nimport { ChromaClient } from 'chromadb';\nimport { ChromaCloudQwenEmbeddingFunction } from '@chroma-core/chroma-cloud-qwen';\n\n// 初始化\nconst embedder = new ChromaCloudQwenEmbeddingFunction({\n apiKey: 'your-api-key',\n model: 'Qwen/Qwen3-Embedding-0.6B',\n});\n\n// 创建集合\nconst collection = await client.createCollection({\n name: 'my-collection',\n embeddingFunction: embedder,\n});\n\n// 添加和查询\nawait collection.add({\n ids: [\"doc1\", \"doc2\", \"doc3\"],\n documents: [\"Document 1\", \"Document 2\", \"Document 3\"],\n});\n\nconst results = await collection.query({\n queryTexts: [\"Sample query\"],\n nResults: 2,\n});\n```\n\n**配置选项**：\n\n| 选项 | 说明 |\n|------|------|\n| `model` | 用于嵌入的模型 |\n| `task` | 生成嵌入的任务 |\n| `instruction_dict` | 任务和目标的自定义指令映射 |\n| `apiKeyEnvVar` | API 密钥环境变量名（默认 CHROMA_API_KEY） |\n\nSources: [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md]()\n\n## 聚合包使用\n\n`@chroma-core/all` 包导出所有嵌入函数，提供一站式导入：\n\n```typescript\nimport {\n OpenAIEmbeddingFunction,\n CohereEmbeddingFunction,\n JinaEmbeddingFunction,\n GoogleGeminiEmbeddingFunction,\n // ... 以及其他所有提供商\n} from '@chroma-core/all';\n\n// 使用任意嵌入函数\nconst openAIEF = new OpenAIEmbeddingFunction({\n apiKey: 'your-api-key',\n modelName: 'text-embedding-3-small'\n});\n```\n\n**包含的提供商**：\n\n- OpenAI\n- Cohere\n- Jina\n- Google Gemini\n- HuggingFace Server\n- Ollama\n- Together AI\n- Voyage AI\n- Cloudflare Worker AI\n- Default Embedding\n\nSources: [clients/new-js/packages/ai-embeddings/all/README.md]()\n\n## 动态加载机制\n\nChromaDB JavaScript 客户端支持嵌入函数的动态加载，通过配置映射实现按需加载：\n\n```typescript\nexport const getEmbeddingFunction = async (\n client: ChromaClient,\n efConfig?: EmbeddingFunctionConfiguration,\n) => {\n // 检查配置类型\n if (efConfig?.type !== \"known\") {\n return undefined;\n }\n\n // 过滤不支持的函数\n if (unsupportedEmbeddingFunctions.has(efConfig.name)) {\n return undefined;\n }\n\n // 获取包名\n const packageName = pythonEmbeddingFunctions[efConfig.name] || efConfig.name;\n\n // 动态导入\n let embeddingFunction = knownEmbeddingFunctions.get(packageName);\n if (!embeddingFunction) {\n try {\n const fullPackageName = `@chroma-core/${packageName}`;\n await import(fullPackageName);\n embeddingFunction = knownEmbeddingFunctions.get(packageName);\n } catch (error) {\n // 动态加载失败\n }\n }\n\n // 使用 buildFromConfig 工厂方法\n if (embeddingFunction.buildFromConfig) {\n return embeddingFunction.buildFromConfig(constructorConfig, client);\n }\n return undefined;\n};\n```\n\n动态加载的优势：\n\n1. **按需加载**：减少初始包体积\n2. **插件化**：支持第三方嵌入函数扩展\n3. **向后兼容**：支持 Python 端的嵌入函数名称映射\n\nSources: [clients/new-js/src/embedding-function.ts]()\n\n## 使用最佳实践\n\n### 安装策略\n\n```bash\n# 仅安装需要的嵌入函数\nnpm install @chroma-core/jina\n\n# 或安装所有嵌入函数\nnpm install @chroma-core/all\n```\n\n### 环境变量配置\n\n大多数嵌入函数支持通过环境变量设置 API 密钥：\n\n```bash\nexport OPENAI_API_KEY=your-openai-key\nexport JINA_API_KEY=your-jina-key\nexport CHROMA_API_KEY=your-chroma-key\nexport MORPH_API_KEY=your-morph-key\nexport XAI_API_KEY=your-xai-key\n```\n\n### 代码组织\n\n```mermaid\ngraph TD\n A[embedding-functions.ts] --> B[统一导出配置]\n B --> C[createCollection 时引用]\n C --> D[数据操作时自动调用]\n \n A1[embedder.ts] --> B\n A2[openai.ts] --> B\n A3[jina.ts] --> B\n```\n\n建议将嵌入函数配置集中管理，便于维护和更换提供商。\n\n## 总结\n\nChromaDB 的嵌入函数集成系统提供了灵活、高效的向量嵌入能力，支持多种云服务和本地模型。通过统一的 Schema 验证机制和动态加载架构，开发者可以轻松切换不同的嵌入提供商，同时保持跨语言的一致性。该系统设计充分考虑了可扩展性，为未来支持更多嵌入模型奠定了基础。\n\n---\n\n\n\n## 存储系统\n\n### Related Pages\n\nRelated topics: [系统架构](#page-architecture), [向量索引系统](#page-vector-index)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/blockstore/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/lib.rs)\n- [rust/blockstore/src/arrow/blockfile.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/blockfile.rs)\n- [rust/blockstore/src/arrow/block/types.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n- [rust/blockstore/src/arrow/root.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n- [rust/blockstore/src/arrow/provider.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n- [rust/blockstore/src/provider.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n- [rust/types/src/sparse_posting_block.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n- [rust/wal3/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/wal3/src/lib.rs)\n \n\n# 存储系统\n\n## 概述\n\nChroma 的存储系统是整个数据库基础设施的核心组件，负责管理向量数据和元数据的持久化存储。该系统采用分层架构设计，主要包括以下核心模块：\n\n- **Blockstore**：块存储抽象层，支持多种后端实现\n- **Arrow Blockfile**：基于 Apache Arrow IPC 格式的列式存储实现\n- **Sparse Posting Block**：稀疏倒排索引块存储\n- **WAL3**：三次写入日志（Write-Ahead Log）机制\n\n存储系统的设计目标是通过统一的 API 抽象，支持内存映射、持久化存储以及远程存储后端，同时保证数据一致性和高性能访问。\n\nSources: [rust/blockstore/src/lib.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/lib.rs)\n\n## 架构分层\n\nChroma 存储系统采用四层架构设计，每一层都有明确的职责边界：\n\n```mermaid\ngraph TD\n A[应用层] --> B[API 层]\n B --> C[Provider 层]\n C --> D[Blockfile 层]\n D --> E[Storage 层]\n \n B1[BlockfileProvider] --> C1[Arrow Blockfile Provider]\n B1 --> B2[HashMap Blockfile Provider]\n \n C1 --> D1[ArrowBlockfileWriter]\n C1 --> D2[ArrowBlockfileReader]\n \n E1[Storage] --> E2[本地文件系统]\n E1 --> E3[远程存储]\n```\n\n### 各层职责\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| API 层 | BlockfileProvider | 统一的读写接口抽象 |\n| Provider 层 | Arrow/HashMap Provider | 特定存储格式的提供者 |\n| Blockfile 层 | ArrowBlockfile | 具体的数据块读写实现 |\n| Storage 层 | Storage | 底层持久化机制 |\n\nSources: [rust/blockstore/src/provider.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n\n## Blockstore 核心抽象\n\n### BlockfileProvider 接口\n\n`BlockfileProvider` 是存储系统的核心抽象接口，提供统一的读写操作入口：\n\n```rust\npub trait ReadKey<'a>:\n Key\n + Into\n + TryFrom<&'a KeyWrapper, Error = InvalidKeyConversion>\n + ArrowReadableKey<'a>\n + Sync\n + 'a\n{\n}\n\npub trait ReadValue<'a>: Value + Readable<'a> + ArrowReadableValue<'a> + Sync + 'a {}\n```\n\n该接口支持两种实现：\n1. **ArrowBlockfileProvider**：基于 Arrow IPC 格式的持久化存储\n2. **HashMapBlockfileProvider**：纯内存存储实现\n\nSources: [rust/blockstore/src/provider.rs:60-90](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n\n### 核心 API 方法\n\n| 方法 | 参数 | 返回值 | 描述 |\n|------|------|--------|------|\n| `read` | `options: BlockfileReaderOptions` | `BlockfileReader` | 读取数据块 |\n| `write` | `options: BlockfileWriterOptions` | `BlockfileWriter` | 写入数据块 |\n| `clear` | - | `Result<(), Box>` | 清空缓存 |\n| `prefetch` | `id`, `prefix_path` | `Result` | 预取数据到缓存 |\n| `storage` | - | `Option>` | 获取底层存储 |\n\nSources: [rust/blockstore/src/provider.rs:120-180](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n\n## Arrow Blockfile 实现\n\n### Arrow Blockfile 概述\n\nArrow Blockfile 是 Chroma 的主要存储实现，基于 Apache Arrow 的 IPC（Inter-Process Communication）格式。这种设计带来以下优势：\n\n- **列式存储**：相同类型的数据连续存储，提升压缩率和扫描效率\n- **零拷贝读取**：通过内存映射实现高效的数据访问\n- **类型安全**：Arrow 格式内置 schema 验证\n\n```mermaid\ngraph LR\n A[写入请求] --> B[BlockDelta]\n B --> C[SparseIndex]\n C --> D[Root]\n D --> E[Block Manager]\n E --> F[持久化存储]\n \n G[读取请求] --> H[Arrow Blockfile Reader]\n H --> I[Footer Parsing]\n I --> J[Record Batch]\n```\n\nSources: [rust/blockstore/src/arrow/blockfile.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/blockfile.rs)\n\n### Block 结构\n\nArrow Blockfile 中的数据块（Block）是存储的最小单元：\n\n```rust\n#[derive(Error, Debug)]\npub enum ArrowLayoutVerificationError {\n #[error(\"Buffer length is not 64 byte aligned\")]\n BufferLengthNotAligned,\n #[error(transparent)]\n IOError(#[from] std::io::Error),\n #[error(transparent)]\n ArrowError(#[from] arrow::error::ArrowError),\n #[error(transparent)]\n InvalidFlatbuffer(#[from] flatbuffers::InvalidFlatbuffer),\n #[error(\"No record batches in footer\")]\n NoRecordBatches,\n #[error(\"More than one record batch in IPC file\")]\n MultipleRecordBatches,\n #[error(\"Invalid message type\")]\n InvalidMessageType,\n #[error(\"Error decoding record batch message as record batch\")]\n RecordBatchDecodeError,\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:1-60](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n### Root 结构与版本管理\n\nRoot 是 Arrow Blockfile 的元数据头部，包含版本信息和块ID列表：\n\n```rust\nimpl RootReader {\n pub(super) fn get_all_block_ids_from_bytes(\n bytes: &[u8],\n id: Uuid,\n ) -> Result, FromBytesError> {\n let mut cursor = std::io::Cursor::new(bytes);\n let arrow_reader = arrow::ipc::reader::FileReader::try_new(&mut cursor, None);\n\n let record_batch = match arrow_reader {\n Ok(mut reader) => match reader.next() {\n Some(Ok(batch)) => batch,\n Some(Err(e)) => return Err(FromBytesError::ArrowError(e)),\n None => {\n return Err(FromBytesError::NoDataError);\n }\n },\n Err(e) => return Err(FromBytesError::ArrowError(e)),\n };\n\n let (version, read_id) = Self::version_and_id_from_record_batch(&record_batch, id)?;\n if read_id != id {\n return Err(FromBytesError::IdMismatch);\n }\n\n Self::block_ids_from_record_batch(&record_batch, version)\n }\n}\n```\n\n版本管理确保数据格式的向前兼容性和向后兼容性。\n\nSources: [rust/blockstore/src/arrow/root.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n### BlockfileWriter 实现\n\n`ArrowUnorderedBlockfileWriter` 是无序写入的实现，适用于高并发场景：\n\n```rust\nimpl ArrowUnorderedBlockfileWriter {\n pub(super) fn new(\n id: Uuid,\n prefix_path: &str,\n block_manager: BlockManager,\n root_manager: RootManager,\n max_block_size_bytes: usize,\n cmek: Option,\n ) -> Self {\n let initial_block = block_manager.create::();\n let sparse_index = SparseIndexWriter::new(initial_block.id);\n // ...\n }\n}\n```\n\nSources: [rust/blockstore/src/arrow/blockfile.rs:100-150](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/blockfile.rs)\n\n## Provider 层实现\n\n### Arrow Blockfile Provider\n\n`ArrowBlockfileProvider` 是生产环境的主要存储提供者：\n\n```rust\n// Fork 操作支持数据分叉\nmatch options.mutation_ordering {\n BlockfileWriterMutationOrdering::Ordered => {\n let file = ArrowOrderedBlockfileWriter::from_root(\n new_id,\n self.block_manager.clone(),\n self.root_manager.clone(),\n new_root,\n options.cmek,\n );\n Ok(BlockfileWriter::ArrowOrderedBlockfileWriter(file))\n }\n BlockfileWriterMutationOrdering::Unordered => {\n let file = ArrowUnorderedBlockfileWriter::from_root(\n new_id,\n self.block_manager.clone(),\n self.root_manager.clone(),\n new_root,\n options.cmek,\n );\n Ok(BlockfileWriter::ArrowUnorderedBlockfileWriter(file))\n }\n}\n```\n\nSources: [rust/blockstore/src/arrow/provider.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n### 写入选项配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `prefix_path` | String | - | 数据路径前缀 |\n| `max_block_size_bytes` | usize | 引擎默认值 | 单个块最大字节数 |\n| `mutation_ordering` | BlockfileWriterMutationOrdering | Ordered | 写入顺序策略 |\n| `fork_from` | Option | None | 从现有块分叉 |\n| `cmek` | Option | None | 客户管理的加密密钥 |\n\nSources: [rust/blockstore/src/arrow/provider.rs:80-120](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n## Sparse Posting Block\n\n稀疏倒排索引块是 Chroma 全文搜索功能的核心数据结构：\n\n```rust\n/// DirectoryBlock 存储每个 posting block 的元数据\n/// body = [ max_offset: u32 LE, max_weight: f32 LE ] × num_entries\npub struct DirectoryBlock(SparsePostingBlock);\n\nimpl DirectoryBlock {\n pub fn new(max_offsets: &[u32], max_weights: &[f32]) -> Result {\n if max_offsets.len() != max_weights.len() {\n return Err(SparsePostingBlockError::MismatchedLengths {\n offsets: max_offsets.len(),\n weights: max_weights.len(),\n });\n }\n // ...\n }\n}\n```\n\n该结构支持高效的词项剪枝，通过 `max_weight` 实现维度级别的权重过滤。\n\nSources: [rust/types/src/sparse_posting_block.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n\n## WAL3 日志系统\n\n### WAL3 概述\n\nWAL3（Write-Ahead Log version 3）是 Chroma 的预写日志系统，确保数据在系统崩溃后能够恢复：\n\n```mermaid\ngraph LR\n A[事务开始] --> B[写入 WAL]\n B --> C[写入主存储]\n C --> D[标记事务完成]\n D --> E[定期 Checkpoint]\n E --> F[清理已持久化日志]\n```\n\nWAL3 的核心设计目标：\n1. **原子性**：事务要么全部成功，要么全部回滚\n2. **持久性**：已提交的事务不会丢失\n3. **恢复能力**：崩溃后能够恢复到一致状态\n\nSources: [rust/wal3/src/lib.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/wal3/src/lib.rs)\n\n### WAL3 数据格式\n\nWAL3 使用紧凑的二进制格式存储事务日志：\n\n| 字段 | 长度 | 说明 |\n|------|------|------|\n| Magic Number | 4 bytes | 标识 WAL3 格式 |\n| Version | 4 bytes | 格式版本号 |\n| Transaction ID | 8 bytes | 递增的事务标识 |\n| Payload Length | 4 bytes | 数据载荷长度 |\n| Payload | Variable | 实际数据 |\n\nSources: [rust/wal3/src/lib.rs:50-100](https://github.com/chroma-core/chroma/blob/main/rust/wal3/src/lib.rs)\n\n## 错误处理机制\n\n### 错误码映射\n\nChroma 存储系统使用统一的错误码体系：\n\n| 错误类型 | 错误码 | 说明 |\n|----------|--------|------|\n| `BlockLoadError::IOError` | Internal | I/O 操作失败 |\n| `BlockLoadError::ArrowError` | Internal | Arrow 解析错误 |\n| `BlockLoadError::CacheError` | Internal | 缓存访问错误 |\n| `FromBytesError::InvalidArgument` | InvalidArgument | 参数验证失败 |\n| `FromBytesError::IdMismatch` | InvalidArgument | ID 不匹配 |\n| `ArrowLayoutVerificationError` | Internal | 布局验证失败 |\n\nSources: [rust/blockstore/src/arrow/block/types.rs:10-40](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n### Arrow Layout 验证\n\nArrow Blockfile 在读取时执行严格的布局验证：\n\n1. **缓冲区对齐检查**：数据缓冲区必须 64 字节对齐\n2. **Magic 标识检查**：验证 Arrow IPC 文件头\n3. **Record Batch 数量检查**：确保只有一个 record batch\n4. **消息类型验证**：验证消息类型正确\n\n```rust\n#[derive(Error, Debug)]\npub enum ArrowLayoutVerificationError {\n #[error(\"Buffer length is not 64 byte aligned\")]\n BufferLengthNotAligned,\n #[error(\"No record batches in footer\")]\n NoRecordBatches,\n #[error(\"More than one record batch in IPC file\")]\n MultipleRecordBatches,\n // ...\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:20-45](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n## 数据流与操作流程\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Provider as BlockfileProvider\n participant Writer as ArrowBlockfileWriter\n participant BlockMgr as BlockManager\n participant Storage as Storage\n\n Client->>Provider: write(options)\n Provider->>Writer: create Writer\n Writer->>BlockMgr: create BlockDelta\n loop 数据写入\n Client->>Writer: set(key, value)\n Writer->>BlockMgr: flush if full\n end\n Writer->>Storage: persist blocks\n Storage-->>Writer: confirm\n Writer-->>Provider: Writer ready\n Provider-->>Client: return Writer\n```\n\nSources: [rust/blockstore/src/arrow/blockfile.rs:80-120](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/blockfile.rs)\n\n### 读取流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Provider as BlockfileProvider\n participant Reader as ArrowBlockfileReader\n participant Storage as Storage\n\n Client->>Provider: read(options)\n Provider->>Reader: create Reader\n Reader->>Storage: load Footer\n Storage-->>Reader: Footer bytes\n Reader->>Reader: parse Record Batch\n Reader-->>Provider: Reader ready\n Provider-->>Client: return Reader\n Client->>Reader: get(key)\n Reader-->>Client: value\n```\n\nSources: [rust/blockstore/src/arrow/root.rs:30-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n## 性能优化\n\n### 块大小配置\n\n| 参数 | 默认值 | 说明 | 调优建议 |\n|------|--------|------|----------|\n| `max_block_size_bytes` | 系统默认值 | 单块最大容量 | 大值减少块数量，小值提高随机访问 |\n| `pl_block_size` | 特定值 | Posting List 块大小 | 影响倒排索引性能 |\n| `hnsw_ef_search` | 可配置 | HNSW 搜索参数 | 影响召回率和延迟 |\n\nSources: [rust/index/src/spann/types.rs:50-80](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### 预取机制\n\nBlockfileProvider 支持数据预取以提高读取性能：\n\n```rust\npub async fn prefetch(\n &self,\n id: &uuid::Uuid,\n prefix_path: &str,\n) -> Result> {\n match self {\n BlockfileProvider::HashMapBlockfileProvider(_) => unimplemented!(),\n BlockfileProvider::ArrowBlockfileProvider(provider) => provider\n .prefetch(id, prefix_path)\n .await\n .map_err(|e| Box::new(e) as _),\n }\n}\n```\n\nSources: [rust/blockstore/src/provider.rs:160-180](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n\n## 安全特性\n\n### CMEK 支持\n\nChroma 存储系统支持客户管理的加密密钥（Customer-Managed Encryption Keys）：\n\n```rust\nbf_options = bf_options.with_cmek(cmek);\n```\n\n每个块文件都可以使用独立的加密配置，确保敏感数据的隔离保护。\n\nSources: [rust/blockstore/src/arrow/provider.rs:50-70](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n## 配置参考\n\n### BlockfileWriterOptions 配置\n\n```rust\nlet mut bf_options = BlockfileWriterOptions::new(prefix_path.to_string())\n .max_block_size_bytes(pl_block_size);\nbf_options = bf_options.unordered_mutations();\nif let Some(cmek) = cmek {\n bf_options = bf_options.with_cmek(cmek);\n}\n```\n\n关键配置项：\n- `prefix_path`：数据存储路径前缀\n- `max_block_size_bytes`：块大小限制\n- `unordered_mutations`：启用无序写入模式\n- `fork`：从现有块分叉创建\n- `cmek`：加密配置\n\nSources: [rust/index/src/spann/types.rs:100-130](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## 总结\n\nChroma 的存储系统是一个精心设计的分层架构，核心特点包括：\n\n1. **统一的抽象层**：通过 `BlockfileProvider` 接口支持多种后端实现\n2. **Arrow 列式存储**：利用 Arrow IPC 格式实现高效的列式数据访问\n3. **稀疏索引支持**：通过 DirectoryBlock 和 PostingBlock 支持全文搜索\n4. **WAL3 日志**：确保事务的原子性和持久性\n5. **安全特性**：支持 CMEK 客户管理加密\n6. **灵活配置**：支持块大小、写入顺序、分叉等高级配置\n\n这套存储系统为 Chroma 的向量数据库功能提供了坚实的数据持久化基础，同时保持了良好的可扩展性和性能。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：chroma-core/chroma\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:546206616 | https://github.com/chroma-core/chroma | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | release_recency=unknown\n\n\n",
"markdown_key": "chroma",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:546206616",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/chroma-core/chroma"
},
{
"evidence_id": "art_4add53223c9947409ac05916314bff2e",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/chroma-core/chroma#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "chroma 说明书",
"toc": [
"Wiki Documentation for https://github.com/chroma-core/chroma",
"Table of Contents",
"Chroma项目概述",
"项目简介",
"系统架构",
"数据模型",
"客户端SDK",
"创建客户端",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# chroma - Doramagic AI Context Pack\n\n> 定位：给用户宿主 AI 装载的开工前上下文。它不代表已经安装、运行或验证目标项目。\n\n## 项目\n\n- canonical_name: `chroma-core/chroma`\n- capability: Search infrastructure for AI\n- expected_user_outcome: Search infrastructure for AI\n\n## 基础边界\n\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 项目事实必须来自 repo evidence、Claim Graph 或明确来源。\n- 遇到未验证能力时，必须标记为待验证，而不是补全为事实。\n- publish_status: `publishable`\n- blocking_gaps: none\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Chroma项目概述**：importance `high`\n - source_paths: README.md, chromadb/__init__.py, Cargo.toml\n- **安装与配置**：importance `high`\n - source_paths: clients/python/pyproject.toml, clients/js/package.json, Dockerfile, docker-compose.yml\n- **系统架构**：importance `high`\n - source_paths: rust/frontend/src/lib.rs, rust/worker/src/lib.rs, go/pkg/sysdb/coordinator/coordinator.go, idl/chromadb/proto/chroma.proto, rust/system/src/lib.rs\n- **数据流与处理流程**：importance `high`\n - source_paths: rust/types/src/operation.rs, rust/worker/src/execution/orchestration/mod.rs, rust/types/src/execution/plan.rs, chromadb/api/segment.py\n- **向量索引系统**：importance `high`\n - source_paths: rust/index/src/hnsw.rs, rust/index/src/spann.rs, rust/index/src/quantization/mod.rs, rust/index/src/sparse/mod.rs, rust/segment/src/local_hnsw.rs\n- **查询执行引擎**：importance `high`\n - source_paths: rust/system/src/execution/operator.rs, rust/types/src/execution/operator.rs, rust/worker/src/execution/operators/knn_hnsw.rs, rust/worker/src/execution/operators/filter.rs, rust/execution/expression/plan.py\n- **Python客户端**：importance `high`\n - source_paths: chromadb/api/client.py, chromadb/api/async_client.py, chromadb/api/models/Collection.py, chromadb/api/models/AsyncCollection.py, chromadb/api/fastapi.py\n- **JavaScript/TypeScript客户端**：importance `medium`\n - source_paths: clients/js/packages/chromadb-core/src/ChromaClient.ts, clients/new-js/packages/chromadb/src/chroma-client.ts, clients/new-js/packages/chromadb/src/api/client.gen.ts, clients/js/packages/chromadb-client/src/index.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:546206616 | https://github.com/chroma-core/chroma | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：chroma-core/chroma\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- issue/PR 响应质量未知（low）：用户无法判断遇到问题后是否有人维护。 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# Wiki Documentation for https://github.com/chroma-core/chroma\n\nGenerated on: 2026-05-10 14:46:12 UTC\n\n## Table of Contents\n\n- [Chroma项目概述](#page-overview)\n- [安装与配置](#page-installation)\n- [系统架构](#page-architecture)\n- [数据流与处理流程](#page-data-flow)\n- [向量索引系统](#page-vector-index)\n- [查询执行引擎](#page-query-execution)\n- [Python客户端](#page-python-client)\n- [JavaScript/TypeScript客户端](#page-javascript-client)\n- [嵌入函数集成](#page-embedding-functions)\n- [存储系统](#page-storage)\n\n\n\n## Chroma项目概述\n\n### Related Pages\n\nRelated topics: [系统架构](#page-architecture), [安装与配置](#page-installation)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n- [rust/types/src/collection_schema.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n- [rust/types/src/metadata.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n- [rust/blockstore/src/arrow/root.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n- [rust/worker/src/execution/operators/execute_task.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/execute_task.rs)\n- [rust/worker/src/execution/operators/materialize_logs.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/materialize_logs.rs)\n- [clients/new-js/packages/chromadb/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/README.md)\n- [examples/xai/README.md](https://github.com/chroma-core/chroma/blob/main/examples/xai/README.md)\n- [schemas/embedding_functions/README.md](https://github.com/chroma-core/chroma/blob/main/schemas/embedding_functions/README.md)\n- [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)\n \n\n# Chroma项目概述\n\n## 项目简介\n\nChroma是一个开源的AI数据基础设施项目，专为向量搜索和嵌入式AI应用设计。它提供了完整的向量数据库功能，支持文档存储、元数据过滤、相似性搜索等核心能力。Chroma的核心目标是简化AI应用的开发流程，让开发者能够快速构建基于向量检索的应用程序。\n\n该项目采用Apache 2.0开源许可证，支持Python和JavaScript/TypeScript双语言客户端，同时提供客户端-服务器模式部署选项。Chroma Cloud是其托管服务，提供serverless向量搜索、混合搜索和全文搜索能力。 Sources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n\n## 系统架构\n\n### 整体架构设计\n\nChroma采用混合架构设计，核心存储层使用Rust语言实现，以确保高性能和数据安全。系统支持多种部署模式，包括本地嵌入式部署和客户端-服务器模式。\n\n```mermaid\ngraph TD\n A[Python Client / JS Client] --> B[Chroma Server]\n A --> C[Embedded Mode]\n B --> D[Rust Worker]\n C --> D\n D --> E[Blockstore]\n D --> F[Record Segment]\n E --> G[Arrow Format Storage]\n F --> H[Log Materialization]\n G --> I[Persistent Storage]\n H --> I\n```\n\n### Rust核心组件\n\nChroma的Rust后端包含多个核心模块，这些模块共同协作完成向量数据的存储和检索工作。\n\n| 组件名称 | 路径位置 | 功能描述 |\n|---------|---------|---------|\n| blockstore | rust/blockstore/ | 块存储管理，使用Apache Arrow格式 |\n| types | rust/types/ | 类型定义和数据模型 |\n| worker | rust/worker/src/execution/ | 任务执行和日志物化处理 |\n| record_segment | - | 记录段读写管理 |\n\nSources: [rust/blockstore/src/arrow/root.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs), [rust/types/src/collection_schema.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n## 数据模型\n\n### Collection Schema\n\nChroma使用Schema来定义Collection的结构和索引配置。每个Schema可以包含多个字段定义和索引配置。\n\n```rust\nSchema::default()\n .create_index(None, VectorIndexConfig {\n space: Some(Space::Cosine),\n embedding_function: None,\n source_key: None,\n hnsw: None,\n spann: None,\n }.into())?\n .create_index(Some(\"category\"), StringInvertedIndexConfig {}.into())?\n```\n\nSources: [rust/types/src/collection_schema.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n### 元数据系统\n\nChroma支持丰富的元数据过滤功能，包括多种比较操作符和表达式组合。\n\n```mermaid\ngraph LR\n A[MetadataComparison] --> B[Primitive Comparisons]\n A --> C[Set Comparisons]\n B --> D[= / != / > / >= / < / <=]\n C --> E[$in / $nin]\n \n F[DocumentOperator] --> G[Contains]\n F --> H[NotContains]\n F --> I[Regex]\n F --> J[NotRegex]\n```\n\n支持的元数据比较操作符包括：`=`, `!=`, `>`, `>=`, `<`, `<=` 以及集合操作符 `$in` 和 `$nin`。文档操作符支持 `Contains`、`NotContains`、`Regex` 和 `NotRegex`。 Sources: [rust/types/src/metadata.rs:1-40](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n\n### 索引类型\n\n| 索引类型 | 说明 | 适用范围 |\n|---------|------|---------|\n| VectorIndex | 向量索引，支持HNSW和Spann | 全局向量字段 |\n| StringInvertedIndex | 字符串倒排索引 | 字符串类型字段 |\n| Spann | Spann向量索引 | 向量字段可选 |\n\nSources: [rust/types/src/collection_schema.rs:1-60](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n## 客户端SDK\n\n### Python客户端\n\nPython客户端是最成熟的客户端实现，支持完整的Chroma功能集。\n\n```python\nimport chromadb\n\n# 创建客户端\nchroma = chromadb.Client()\n\n# 创建Collection\ncollection = chroma.create_collection(\n name=\"my-collection\",\n metadata={\"description\": \"My first collection\"}\n)\n\n# 添加文档\ncollection.add(\n documents=[\"Document 1\", \"Document 2\"],\n metadatas=[{\"source\": \"doc1\"}, {\"source\": \"doc2\"}],\n ids=[\"id1\", \"id2\"]\n)\n\n# 查询\nresults = collection.query(\n query_texts=[\"This is a query document\"],\n n_results=2,\n where={\"metadata_field\": \"is_equal_to_this\"}\n)\n```\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md), [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)\n\n### JavaScript/TypeScript客户端\n\n新的JavaScript客户端采用模块化设计，分为多个独立包。\n\n```typescript\nimport { ChromaClient } from \"chromadb\";\n\nconst chroma = new ChromaClient();\nconst collection = await chroma.createCollection({ name: \"test-from-js\" });\n\nfor (let i = 0; i < 20; i++) {\n await collection.add({\n ids: [\"test-id-\" + i.toString()],\n embeddings: [[1, 2, 3, 4, 5]],\n documents: [\"test\"],\n });\n}\n```\n\nSources: [clients/new-js/packages/chromadb/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/README.md)\n\n## 嵌入函数系统\n\n### 架构设计\n\nChroma的嵌入函数系统采用插件化架构，支持多种嵌入服务提供商。每个嵌入函数都有对应的JSON Schema进行配置验证。\n\n```mermaid\ngraph TD\n A[Embedding Function] --> B[Schema Validation]\n B --> C[Config Validation]\n C --> D[API Client]\n D --> E[Embedding Service]\n \n F[OpenAI Schema] --> B\n G[Jina Schema] --> B\n H[TogetherAI Schema] --> B\n I[Qwen Schema] --> B\n```\n\nSources: [schemas/embedding_functions/README.md](https://github.com/chroma-core/chroma/blob/main/schemas/embedding_functions/README.md)\n\n### 支持的嵌入提供商\n\n| 提供商 | NPM包名 | 支持模型 |\n|-------|---------|---------|\n| OpenAI | 内置 | text-embedding-ada-002 等 |\n| Jina | @chroma-core/jina | jina-embeddings-v2-base-en |\n| Together AI | @chroma-core/together-ai | togethercomputer/m2-bert-80M-8k-retrieval |\n| Qwen | @chroma-core/chroma-cloud-qwen | Qwen3-Embedding-0.6B |\n| xAI | 示例 | xAI SDK集成 |\n\nSources: [clients/new-js/packages/ai-embeddings/jina/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/jina/README.md), [clients/new-js/packages/ai-embeddings/together-ai/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/together-ai/README.md), [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md)\n\n### 配置验证\n\n每个嵌入函数都使用JSON Schema Draft-07规范进行配置验证，确保跨语言兼容性。\n\n```python\nfrom chromadb.utils.embedding_functions.schemas import validate_config\n\nconfig = {\n \"api_key_env_var\": \"CHROMA_OPENAI_API_KEY\",\n \"model_name\": \"text-embedding-ada-002\"\n}\nvalidate_config(config, \"openai\")\n```\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)\n\n## 执行流程\n\n### 日志物化流程\n\nChroma使用日志物化（Log Materialization）来处理数据变更，确保数据的一致性和持久性。\n\n```mermaid\ngraph LR\n A[LogRecord] --> B[MaterializeLogInput]\n B --> C[MaterializeLogOperator]\n C --> D[PartitionedMaterializeLogsResult]\n D --> E[Persistent Storage]\n \n F[RecordSegmentReader] -.-> C\n G[Offset IDs] -.-> C\n H[Plan Options] -.-> C\n```\n\nSources: [rust/worker/src/execution/operators/materialize_logs.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/materialize_logs.rs)\n\n### 任务执行流程\n\nAttached Function执行涉及记录段读取、日志偏移量处理和分片管理。\n\n```mermaid\ngraph TD\n A[ExecuteAttachedFunctionInput] --> B[Record Segment Reader]\n B --> C{Is Rebuild / Backfill?}\n C -->|Yes| D[Output Record Segment Reader]\n C -->|No| E[Standard Processing]\n D --> F[Process Materialized Logs]\n E --> F\n F --> G[Log Offset Handling]\n G --> H[Segment Shard Processing]\n H --> I[ExecuteAttachedFunctionOutput]\n```\n\nSources: [rust/worker/src/execution/operators/execute_task.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/execute_task.rs)\n\n## 部署方式\n\n### 本地部署\n\n使用pip安装Python客户端即可开始本地开发：\n\n```bash\npip install chromadb\n```\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n\n### 客户端-服务器模式\n\n```bash\nchroma run --path /chroma_db_path\n```\n\n### 云端部署\n\nChroma Cloud提供托管服务，支持serverless向量搜索、混合搜索和全文搜索。\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n\n### Terraform部署示例\n\n支持使用Terraform在DigitalOcean上自动化部署Chroma实例：\n\n```bash\nexport TF_VAR_chroma_release=\"0.4.12\"\nexport TF_VAR_region=\"ams2\"\nexport TF_VAR_public_access=\"true\"\nexport TF_VAR_enable_auth=\"true\"\nexport TF_VAR_auth_type=\"token\"\nterraform apply -auto-approve\n```\n\nSources: [examples/deployments/do-terraform/README.md](https://github.com/chroma-core/chroma/blob/main/examples/deployments/do-terraform/README.md)\n\n## 错误处理\n\n### 错误码体系\n\nChroma使用统一的错误码体系来分类不同类型的错误：\n\n| 错误码 | 含义 | 触发场景 |\n|-------|------|---------|\n| InvalidArgument | 无效参数 | 参数验证失败、ID不匹配 |\n| Internal | 内部错误 | Arrow格式错误、数据缺失 |\n| NotFound | 未找到 | 记录不存在 |\n| AlreadyExists | 已存在 | 重复创建 |\n\nSources: [rust/blockstore/src/arrow/root.rs:1-30](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n## 相关资源\n\n- 官方文档：https://docs.trychroma.com/\n- 社区Discord：https://discord.gg/MMeYNTmh3x\n- GitHub仓库：https://github.com/chroma-core/chroma\n- Homepage：https://www.trychroma.com/\n\n### 示例应用\n\nChroma仓库包含多个示例应用，展示了如何集成不同的AI服务：\n\n- **xAI集成**：展示如何使用xAI SDK进行文档问答\n- **Movies示例**：演示在Web应用中使用Chroma存储和检索电影数据\n- **部署示例**：提供Terraform配置用于云端部署\n\nSources: [examples/xai/README.md](https://github.com/chroma-core/chroma/blob/main/examples/xai/README.md), [sample_apps/movies/README.md](https://github.com/chroma-core/chroma/blob/main/sample_apps/movies/README.md)\n\n---\n\n\n\n## 安装与配置\n\n### Related Pages\n\nRelated topics: [Chroma项目概述](#page-overview)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [clients/python/pyproject.toml](https://github.com/chroma-core/chroma/blob/main/clients/python/pyproject.toml)\n- [clients/js/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/package.json)\n- [Dockerfile](https://github.com/chroma-core/chroma/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/chroma-core/chroma/blob/main/docker-compose.yml)\n \n\n# 安装与配置\n\n## 概述\n\nChroma 是一个开源的 AI 向量数据基础设施，提供向量存储、检索和混合搜索能力。本章节详细介绍 Chroma 的多种安装方式和配置选项，帮助开发者根据不同使用场景选择合适的部署方案。\n\nChroma 支持三种主要的部署模式：\n\n| 部署模式 | 适用场景 | 数据持久化 |\n|---------|---------|-----------|\n| Python 客户端嵌入模式 | 本地开发、原型验证 | 本地文件系统 |\n| 客户端-服务器模式 | 生产环境、多客户端访问 | 可配置存储后端 |\n| Docker 容器化部署 | 微服务架构、DevOps | Docker Volume |\n\nSources: [README.md](README.md)\n\n---\n\n## Python 客户端安装\n\n### 环境要求\n\nChroma Python 客户端支持 Python 3.8 及以上版本。建议使用虚拟环境进行安装以避免依赖冲突。\n\n### 安装方式\n\n#### 通过 pip 安装（推荐）\n\n```bash\npip install chromadb\n```\n\nSources: [README.md](README.md)\n\n#### 通过源码安装\n\n```bash\ngit clone https://github.com/chroma-core/chroma.git\ncd chroma\npip install -e .\n```\n\n#### 验证安装\n\n```python\nimport chromadb\nprint(chromadb.__version__)\n```\n\n### 核心依赖\n\nChroma Python 客户端的依赖管理通过 `pyproject.toml` 配置，主要依赖包括：\n\n| 依赖包 | 用途 |\n|-------|------|\n| `onnxruntime` | 向量计算引擎 |\n| `tokenizers` | 文本分词处理 |\n| `hnswlib` | HNSW 近似最近邻索引 |\n| `clickhouse-connect` | 可选：ClickHouse 后端支持 |\n\nSources: [clients/python/pyproject.toml](clients/python/pyproject.toml)\n\n---\n\n## JavaScript/TypeScript 客户端安装\n\n### 环境要求\n\n- Node.js 18.0 或更高版本\n- npm、yarn 或 pnpm 包管理器\n\n### 安装方式\n\n```bash\n# 使用 npm\nnpm install chromadb\n\n# 使用 yarn\nyarn add chromadb\n\n# 使用 pnpm\npnpm add chromadb\n```\n\nSources: [README.md](README.md)\n\n### 客户端包结构\n\n新版本 JavaScript 客户端 (`new-js`) 包含多个子包：\n\n| 包名 | 功能描述 |\n|-----|---------|\n| `@chroma-core/ai-embeddings-common` | 嵌入函数公共工具库 |\n| `@chroma-core/ai-embeddings` | AI 嵌入功能实现 |\n| `@chroma-core/chromadb` | 核心客户端实现 |\n\nSources: [clients/new-js/packages/ai-embeddings/common/README.md](clients/new-js/packages/ai-embeddings/common/README.md)\n\n### 基本使用示例\n\n```javascript\nimport { ChromaClient } from \"chromadb\";\n\nconst chroma = new ChromaClient();\nconst collection = await chroma.createCollection({ name: \"test-from-js\" });\n\nawait collection.add({\n ids: [\"test-id-1\"],\n embeddings: [[1, 2, 3, 4, 5]],\n documents: [\"test document\"],\n});\n```\n\nSources: [clients/new-js/packages/chromadb/README.md](clients/new-js/packages/chromadb/README.md)\n\n---\n\n## Docker 部署\n\n### 前置条件\n\n- Docker Engine 20.10 或更高版本\n- Docker Compose 2.0 或更高版本（可选）\n\n### 使用 Dockerfile 构建\n\nChroma 提供官方的 Dockerfile 用于构建自定义镜像：\n\n```dockerfile\nFROM python:3.9-slim\n\nWORKDIR /app\n\n# 安装系统依赖\nRUN apt-get update && apt-get install -y \\\n build-essential \\\n && rm -rf /var/lib/apt/lists/*\n\n# 复制应用代码\nCOPY . /app\n\n# 安装 Python 依赖\nRUN pip install --no-cache-dir -e .\n\n# 暴露端口\nEXPOSE 8000\n\n# 启动命令\nCMD [\"chroma\", \"run\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\n```\n\nSources: [Dockerfile](Dockerfile)\n\n### 使用 Docker Compose 编排\n\nDocker Compose 提供了快速启动完整 Chroma 服务的配置：\n\n```yaml\nversion: '3.8'\n\nservices:\n chroma:\n build: .\n ports:\n - \"8000:8000\"\n volumes:\n - chroma_data:/chroma/chroma_db_path\n environment:\n - CHROMA_SERVER_AUTH_CREDENTIALS=admin:password\n - CHROMA_SERVER_AUTH_PROVIDER=basic\n\nvolumes:\n chroma_data:\n```\n\nSources: [docker-compose.yml](docker-compose.yml)\n\n### 启动服务\n\n```bash\n# 仅启动 Chroma 服务\ndocker-compose up -d\n\n# 构建并启动\ndocker-compose up --build\n\n# 查看日志\ndocker-compose logs -f chroma\n\n# 停止服务\ndocker-compose down\n```\n\n---\n\n## 客户端-服务器模式配置\n\n当需要多客户端访问或生产环境部署时，使用 Chroma 的客户端-服务器模式。\n\n### 启动服务器\n\n```bash\n# 基础启动\nchroma run --path /chroma_db_path\n\n# 指定端口和主机\nchroma run --host 0.0.0.0 --port 8000 --path /chroma_db_path\n```\n\nSources: [README.md](README.md)\n\n### 服务器认证配置\n\nChroma 支持基于 Token 和 Basic Auth 两种认证方式（v0.4.7+）：\n\n| 认证类型 | 环境变量 | 说明 |\n|---------|---------|------|\n| Token 认证 | `CHROMA_SERVER_AUTH_CREDENTIALS` | 设置 Token 密钥 |\n| Basic Auth | `CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER` | 设置为 `chromadb.auth.basic.BasicAuthenticationServerProvider` |\n| CORS 配置 | `CHROMA_SERVER_CORS_ALLOWED_ORIGINS` | 允许的跨域来源 |\n\nSources: [examples/deployments/do-terraform/README.md](examples/deployments/do-terraform/README.md)\n\n### API 密钥配置\n\n对于 Chroma Cloud 服务，需要配置 API 密钥：\n\n```bash\nexport CHROMA_API_KEY=your-api-key\n```\n\nSources: [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md](clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md)\n\n### 连接客户端\n\n#### Python 客户端连接\n\n```python\nimport chromadb\n\n# 连接远程服务器\nclient = chromadb.HttpClient(\n host=\"http://localhost:8000\",\n headers={\"Authorization\": \"Bearer your-token\"}\n)\n\n# 使用 Cloud 服务\nclient = chromadb.Client(\n chroma_client_implementation=chromadb.auth.AuthenticatedClient,\n api_key=\"your-api-key\"\n)\n```\n\n#### JavaScript 客户端连接\n\n```javascript\nimport { ChromaClient } from \"chromadb\";\n\n// 连接远程服务器\nconst chroma = new ChromaClient({\n path: \"http://localhost:8000\"\n});\n```\n\n---\n\n## 环境变量配置\n\n### 完整环境变量列表\n\n| 环境变量 | 默认值 | 说明 |\n|---------|-------|------|\n| `CHROMA_DB_IMPL` | `duckdb+parquet` | 数据库实现类型 |\n| `CHROMA_SERVER_HOST` | `localhost` | 服务器主机地址 |\n| `CHROMA_SERVER_PORT` | `8000` | 服务器端口 |\n| `CHROMA_SERVER_CORS_ALLOWED_ORIGINS` | `*` | 允许的 CORS 来源 |\n| `CHROMA_SERVER_AUTH_CREDENTIALS` | - | 认证凭证 |\n| `CHROMA_SERVER_AUTH_PROVIDER` | - | 认证提供者 |\n| `CHROMA_API_KEY` | - | Cloud API 密钥 |\n\nSources: [README.md](README.md), [sample_apps/movies/README.md](sample_apps/movies/README.md)\n\n### 示例：生产环境配置\n\n```bash\n# 环境变量配置示例\nexport CHROMA_SERVER_HOST=0.0.0.0\nexport CHROMA_SERVER_PORT=8000\nexport CHROMA_SERVER_CORS_ALLOWED_ORIGINS=\"https://your-app.com\"\nexport CHROMA_SERVER_AUTH_CREDENTIALS=\"your-secure-password\"\nexport CHROMA_SERVER_AUTH_PROVIDER=\"chromadb.auth.basic.BasicAuthenticationServerProvider\"\n```\n\n---\n\n## 嵌入函数配置\n\n### 内置嵌入函数\n\nChroma 提供多种内置嵌入函数，支持不同的 AI 提供商：\n\n| 提供商 | 模型 | 配置参数 |\n|-------|-----|---------|\n| OpenAI | `text-embedding-ada-002` | `api_key_env_var`, `model_name` |\n| Google Docs | - | `credentials`, `token` |\n| xAI | Qwen3-Embedding-0.6B | `api_key_env_var`, `model`, `task` |\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](chromadb/utils/embedding_functions/schemas/README.md), [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md](clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md)\n\n### 嵌入函数配置验证\n\nChroma 使用 JSON Schema 对嵌入函数配置进行验证，确保跨语言兼容性：\n\n```python\nfrom chromadb.utils.embedding_functions.schemas import validate_config\n\n# 验证 OpenAI 配置\nconfig = {\n \"api_key_env_var\": \"CHROMA_OPENAI_API_KEY\",\n \"model_name\": \"text-embedding-ada-002\"\n}\nvalidate_config(config, \"openai\")\n```\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](chromadb/utils/embedding_functions/schemas/README.md)\n\n---\n\n## 快速入门示例\n\n### 本地模式（Python）\n\n```python\nimport chromadb\n\n# 创建客户端（本地模式）\nclient = chromadb.PersistentClient(path=\"./chroma_db\")\n\n# 创建集合\ncollection = client.create_collection(name=\"my_collection\")\n\n# 添加数据\ncollection.add(\n documents=[\"第一个文档\", \"第二个文档\", \"第三个文档\"],\n ids=[\"id1\", \"id2\", \"id3\"],\n metadatas=[{\"source\": \"docs\"}, {\"source\": \"docs\"}, {\"source\": \"api\"}]\n)\n\n# 查询数据\nresults = collection.query(\n query_texts=[\"查询文本\"],\n n_results=2\n)\n\nprint(results)\n```\n\n### 服务器模式（Python）\n\n```python\nimport chromadb\n\n# 连接服务器\nclient = chromadb.HttpClient(host=\"http://localhost:8000\")\n\n# 后续操作与本地模式相同\ncollection = client.get_collection(name=\"my_collection\")\nresults = collection.query(\n query_texts=[\"查询文本\"],\n n_results=2,\n where={\"source\": \"docs\"} # 元数据过滤\n)\n```\n\nSources: [README.md](README.md)\n\n---\n\n## 部署架构\n\n### 单节点部署架构\n\n```mermaid\ngraph TD\n A[Client Application] -->|HTTP API| B[Chroma Server]\n B --> C[DuckDB + Parquet]\n B --> D[HNSW Index]\n C --> E[Persistent Storage]\n D --> E\n \n F[Embedding Function] -->|Compute Embeddings| B\n G[OpenAI API] -->|Optional| F\n```\n\n### Docker 部署架构\n\n```mermaid\ngraph TD\n A[External Clients] -->|HTTP| B[Docker Container]\n B --> C[Chroma Server]\n C --> D[(DuckDB)]\n C --> E[HNSW Index]\n D --> F[Volume: chroma_data]\n E --> F\n \n G[Embedding Service] -->|Compute| C\n```\n\n### 生产环境部署架构\n\n```mermaid\ngraph LR\n A[Web App] -->|API Requests| B[Load Balancer]\n B --> C1[Chroma Node 1]\n B --> C2[Chroma Node 2]\n B --> C3[Chroma Node N]\n \n C1 --> D[(Shared Storage)]\n C2 --> D\n C3 --> D\n \n D --> E[S3 / NFS]\n```\n\n---\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|-----|---------|---------|\n| 连接超时 | 服务未启动或端口错误 | 确认服务运行状态和端口配置 |\n| 认证失败 | Token 或 Basic Auth 配置错误 | 检查环境变量配置 |\n| 嵌入维度不匹配 | 不同嵌入函数生成的向量维度不同 | 确保同一集合使用相同的嵌入函数 |\n| 存储空间不足 | Parquet 文件过大 | 配置数据分片或清理旧数据 |\n\n### 日志查看\n\n```bash\n# Docker 环境查看日志\ndocker-compose logs chroma\n\n# 直接运行查看实时日志\nchroma run --path /chroma_db_path --verbose\n```\n\n---\n\n## 相关资源\n\n- [官方文档](https://docs.trychroma.com/)\n- [GitHub 仓库](https://github.com/chroma-core/chroma)\n- [Discord 社区](https://discord.gg/MMeYNTmh3x)\n- [Chroma Cloud](https://trychroma.com/)\n\n---\n\n\n\n## 系统架构\n\n### Related Pages\n\nRelated topics: [数据流与处理流程](#page-data-flow), [向量索引系统](#page-vector-index), [存储系统](#page-storage)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/frontend/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/frontend/src/lib.rs)\n- [rust/worker/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/lib.rs)\n- [go/pkg/sysdb/coordinator/coordinator.go](https://github.com/chroma-core/chroma/blob/main/go/pkg/sysdb/coordinator/coordinator.go)\n- [idl/chromadb/proto/chroma.proto](https://github.com/chroma-core/chroma/blob/main/idl/chromadb/proto/chroma.proto)\n- [rust/system/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/system/src/lib.rs)\n \n\n# 系统架构\n\n## 概述\n\nChroma 是一个开源的 AI 向量数据库，专为存储和检索高维向量数据而设计。系统采用分布式架构，包含多个核心组件协同工作，以提供高效的向量存储、索引和查询能力。\n\nChroma 的系统架构遵循微服务设计原则，将不同的功能模块分离为独立的服务组件，通过 gRPC 协议进行进程间通信。系统支持多租户架构，能够在单一部署中服务多个 tenants 和 databases。\n\n## 系统架构图\n\n```mermaid\ngraph TD\n subgraph Client[\"客户端层\"]\n JS[JavaScript Client]\n Python[Python Client]\n end\n\n subgraph Frontend[\"前端服务\"]\n API[REST/gRPC API]\n Auth[认证模块]\n end\n\n subgraph Worker[\"Worker 服务\"]\n QueryEngine[查询引擎]\n Indexing[索引服务]\n Blockstore[块存储]\n end\n\n subgraph Coordinator[\"协调器\"]\n SysDB[系统数据库]\n TenantMgr[租户管理]\n CollectionMgr[集合管理]\n end\n\n subgraph Storage[\"存储层\"]\n Arrow[Arrow Blockfiles]\n HNSW[HNSW 索引]\n Log[预写日志]\n end\n\n JS --> API\n Python --> API\n API --> Auth\n Auth --> QueryEngine\n QueryEngine --> Indexing\n Indexing --> Blockstore\n Coordinator --> SysDB\n QueryEngine --> Coordinator\n Blockstore --> Arrow\n Indexing --> HNSW\n```\n\n## 核心组件\n\n### 前端服务 (Frontend)\n\n前端服务是 Chroma 系统的入口点，负责处理客户端请求并进行初步验证。源代码显示前端模块采用 Rust 实现，提供了核心的 API 接口。\n\n**主要职责：**\n- 接收并验证客户端请求\n- 处理认证和授权\n- 请求路由和负载均衡\n- 返回标准化的响应格式\n\n**模块位置：** `rust/frontend/src/lib.rs`\n\n### Worker 服务\n\nWorker 是 Chroma 系统中的核心计算节点，负责执行实际的向量操作。每个 Worker 节点可以独立处理查询和索引任务。\n\n**主要职责：**\n- 执行向量相似度搜索\n- 管理 HNSW 索引\n- 处理元数据过滤\n- 存储和检索块数据\n\n**核心子模块：**\n\n| 模块 | 功能 | 源码位置 |\n|------|------|----------|\n| 查询引擎 | 处理向量查询请求 | `rust/worker/src/lib.rs` |\n| 索引服务 | 管理 HNSW/SPANN 索引 | `rust/index/src/` |\n| 块存储 | 持久化向量数据 | `rust/blockstore/src/` |\n\n**块存储架构：**\n\n```mermaid\ngraph LR\n subgraph Blockfile[\"Blockfile 结构\"]\n Header[文件头]\n Body[数据体]\n Footer[文件尾]\n end\n\n subgraph ArrowFormat[\"Arrow IPC 格式\"]\n RecordBatch[Record Batch]\n Schema[Schema 元数据]\n end\n\n Header --> RecordBatch\n RecordBatch --> Body\n Body --> Footer\n```\n\nChroma 使用 Apache Arrow 格式作为底层存储格式，支持高效的列式数据存储和读取。Blockfile 是数据存储的基本单元，包含文件头、数据体和文件尾三部分。\n\nSources: [rust/blockstore/src/arrow/root.rs:1-30](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n### 协调器 (Coordinator)\n\n协调器是系统的中央控制组件，使用 Go 语言实现。它负责管理系统的元数据和全局状态。\n\n**主要职责：**\n- 管理租户和数据库元数据\n- 协调集合的创建和删除\n- 维护系统拓扑信息\n- 处理分布式事务\n\n**协调器结构：**\n\n| 组件 | 功能 | 描述 |\n|------|------|------|\n| SysDB | 系统数据库 | 存储租户、数据库、集合的元数据 |\n| TenantManager | 租户管理器 | 管理租户的生命周期 |\n| CollectionManager | 集合管理器 | 管理集合的创建、删除和分片 |\n\nSources: [go/pkg/sysdb/coordinator/coordinator.go:1-50](https://github.com/chroma-core/chroma/blob/main/go/pkg/sysdb/coordinator/coordinator.go)\n\n## 通信协议\n\n### gRPC 接口定义\n\nChroma 使用 Protocol Buffers 定义服务接口，支持类型安全的跨语言通信。\n\n**核心服务定义：**\n\n```protobuf\n// 来源: idl/chromadb/proto/chroma.proto\nservice Chroma {\n rpc CreateCollection(CreateCollectionRequest) returns (CreateCollectionResponse);\n rpc GetCollection(GetCollectionRequest) returns (GetCollectionResponse);\n rpc DeleteCollection(DeleteCollectionRequest) returns (DeleteCollectionResponse);\n rpc Add(AddRequest) returns (AddResponse);\n rpc Get(GetRequest) returns (GetResponse);\n rpc Query(QueryRequest) returns (QueryResponse);\n}\n```\n\n**查询请求参数：**\n\n| 参数名 | 类型 | 描述 |\n|--------|------|------|\n| `query_embeddings` | Vec\\\\> | 查询向量 |\n| `n_results` | int | 返回结果数量 |\n| `where` | Where | 元数据过滤条件 |\n| `include` | Vec\\ | 返回包含的字段 |\n\nSources: [idl/chromadb/proto/chroma.proto:1-100](https://github.com/chroma-core/chroma/blob/main/idl/chromadb/proto/chroma.proto)\n\n### 消息类型\n\n系统定义了丰富的消息类型用于客户端与服务端之间的数据交换。\n\n```mermaid\nclassDiagram\n class GetRequest {\n +collection_id: String\n +ids: Vec~String~\n +where: Option~Where~\n +include: Vec~String~\n }\n class QueryRequest {\n +collection_id: String\n +query_embeddings: Vec~Vec~float~~\n +n_results: int\n +where: Option~Where~\n +query_texts: Option~Vec~String~~\n }\n class GetResponse {\n +ids: Vec~String~\n +embeddings: Option~Vec~Vec~float~~\n +documents: Option~Vec~String~\n +metadatas: Option~Vec~Metadata~\n }\n```\n\n## 数据模型\n\n### 集合 (Collection)\n\n集合是 Chroma 中的基本数据组织单位，每个集合包含一组相关的向量数据。\n\n```rust\n// 集合属性\nstruct Collection {\n id: CollectionUuid, // 唯一标识符\n name: String, // 集合名称\n tenant_id: String, // 租户标识\n database_name: String, // 数据库名称\n dimension: Option, // 向量维度\n get_index: Option, // 索引配置\n metadata: Option,\n created_at: Timestamp,\n version: i32,\n}\n```\n\nSources: [rust/types/src/collection_schema.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n### 索引配置\n\nChroma 支持多种索引类型以优化查询性能。\n\n| 索引类型 | 描述 | 适用场景 |\n|----------|------|----------|\n| HNSW | 分层可导航小世界图 | 高精度向量搜索 |\n| SPANN | 基于磁盘的向量索引 | 超大规模向量数据 |\n| String Inverted Index | 字符串倒排索引 | 元数据过滤 |\n| Vector Index | 向量索引 | 相似度搜索 |\n\n**向量索引配置示例：**\n\n```rust\nVectorIndexConfig {\n space: Some(Space::Cosine), // 距离度量\n embedding_function: None, // embedding 函数\n source_key: None, // 源 key\n hnsw: None, // HNSW 参数\n spann: None, // SPANN 参数\n}\n```\n\nSources: [rust/types/src/collection_schema.rs:100-150](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n### 过滤条件\n\nChroma 支持丰富的元数据过滤功能。\n\n```mermaid\ngraph TD\n A[Where 过滤条件] --> B[MetadataComparison]\n A --> C[WhereDocumentOperator]\n B --> D[Primitive]\n B --> E[Set Operation]\n D --> F[Equal / NotEqual]\n D --> G[Greater / Less]\n D --> H[Contains / StartsWith]\n C --> I[Contains / NotContains]\n C --> J[Regex / NotRegex]\n```\n\n**支持的比较操作：**\n\n| 操作类型 | 描述 | 示例 |\n|----------|------|------|\n| `$eq` | 等于 | `{\"key\": {\"$eq\": \"value\"}}` |\n| `$ne` | 不等于 | `{\"key\": {\"$ne\": 10}}` |\n| `$gt` | 大于 | `{\"key\": {\"$gt\": 5}}` |\n| `$lt` | 小于 | `{\"key\": {\"$lt\": 100}}` |\n| `$gte` | 大于等于 | `{\"key\": {\"$gte\": 1}}` |\n| `$lte` | 小于等于 | `{\"key\": {\"$lte\": 10}}` |\n\nSources: [rust/types/src/metadata.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n\n## 系统拓扑\n\nChroma 支持多区域部署，允许在不同云提供商的区域中部署 Worker 节点。\n\n```mermaid\ngraph TD\n subgraph Topology[\"系统拓扑\"]\n subgraph Region1[\"区域 1\"]\n WR1[Worker Region 1]\n end\n subgraph Region2[\"区域 2\"]\n WR2[Worker Region 2]\n end\n subgraph RegionN[\"区域 N\"]\n WR3[Worker Region N]\n end\n end\n\n Coordinator --> WR1\n Coordinator --> WR2\n Coordinator --> WR3\n```\n\n**拓扑配置结构：**\n\n```rust\npub struct Topology {\n pub name: TopologyName, // 拓扑名称\n pub regions: Vec, // 包含的区域列表\n pub config: T, // 拓扑配置\n}\n\npub struct ProviderRegion {\n pub name: RegionName, // 区域名称\n pub provider: String, // 云提供商 (aws/gcp/azure)\n pub region: String, // 区域标识\n pub config: T, // 区域配置\n}\n```\n\nSources: [rust/types/src/topology.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n\n## 请求处理流程\n\n### 客户端请求流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Frontend\n participant Coordinator\n participant Worker\n participant Storage\n\n Client->>Frontend: 发起请求\n Frontend->>Frontend: 认证和验证\n Frontend->>Coordinator: 获取元数据\n Coordinator->>Frontend: 返回集合信息\n Frontend->>Worker: 路由查询请求\n Worker->>Worker: 执行向量搜索\n Worker->>Storage: 读取块数据\n Storage->>Worker: 返回数据\n Worker->>Frontend: 返回结果\n Frontend->>Client: 响应结果\n```\n\n### 查询请求处理\n\n1. **请求验证**：Frontend 接收并验证查询请求参数\n2. **元数据获取**：从 Coordinator 获取集合的配置信息\n3. **索引定位**：根据查询条件确定需要扫描的索引\n4. **向量搜索**：在 Worker 节点上执行 HNSW 或其他索引搜索\n5. **结果聚合**：合并多个 Worker 的结果并排序\n6. **元数据过滤**：应用 where 条件过滤最终结果\n7. **响应构建**：根据 include 参数构建响应数据\n\nSources: [rust/system/src/lib.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/system/src/lib.rs)\n\n## 部署架构\n\n### 单一节点部署\n\n在开发和测试环境中，Chroma 可以以单节点模式运行，所有组件运行在同一个进程中。\n\n```yaml\n# 单节点配置示例\nchroma:\n server:\n host: \"0.0.0.0\"\n port: 8000\n storage:\n type: \"local\"\n path: \"/chroma_db\"\n```\n\n### 分布式部署\n\n生产环境推荐使用分布式架构部署：\n\n| 组件 | 副本数 | 职责 |\n|------|--------|------|\n| Frontend | 2-3 | 高可用 API 服务 |\n| Coordinator | 3 | 高可用元数据管理 |\n| Worker | N | 弹性扩展的计算节点 |\n\n```mermaid\ngraph TB\n subgraph LoadBalancer[\"负载均衡器\"]\n LB[Load Balancer]\n end\n\n subgraph FrontendCluster[\"Frontend 集群\"]\n FE1[Frontend 1]\n FE2[Frontend 2]\n end\n\n subgraph CoordinatorCluster[\"Coordinator 集群\"]\n C1[Coordinator 1]\n C2[Coordinator 2]\n C3[Coordinator 3]\n end\n\n subgraph WorkerCluster[\"Worker 集群\"]\n W1[Worker 1]\n W2[Worker 2]\n W3[Worker N]\n end\n\n LB --> FE1\n LB --> FE2\n FE1 --> C1\n FE2 --> C1\n C1 <--> C2\n C2 <--> C3\n FE1 --> W1\n FE1 --> W2\n FE2 --> W2\n FE2 --> W3\n```\n\n## 关键技术特性\n\n### Arrow 存储格式\n\nChroma 使用 Apache Arrow 作为底层存储格式，带来以下优势：\n\n- **列式存储**：支持高效的列投影操作\n- **零拷贝读取**：避免不必要的数据复制\n- **统一数据接口**：支持多种编程语言\n- **压缩友好**：便于应用压缩算法\n\n```rust\n// Arrow Blockfile 读取流程\nlet arrow_reader = arrow::ipc::reader::FileReader::try_new(&mut cursor, None);\nlet record_batch = reader.next(); // 读取 Record Batch\nlet block_ids = Self::block_ids_from_record_batch(&record_batch, version);\n```\n\nSources: [rust/blockstore/src/arrow/root.rs:20-40](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n### 多语言客户端支持\n\nChroma 提供多语言 SDK 支持：\n\n| 语言 | 包名 | 源码位置 |\n|------|------|----------|\n| Python | `chromadb` | `clients/python/` |\n| JavaScript | `chromadb` | `clients/js/` |\n| Go | `chromadb-go` | `clients/go/` |\n\n**Python 客户端示例：**\n\n```python\nfrom chromadb import ChromaClient\n\nclient = ChromaClient()\ncollection = client.create_collection(\"my_collection\")\ncollection.add(\n ids=[\"1\", \"2\"],\n embeddings=[[1.0, 2.0], [3.0, 4.0]],\n documents=[\"doc1\", \"doc2\"]\n)\nresults = collection.query(\n query_embeddings=[[1.0, 2.0]],\n n_results=1\n)\n```\n\nSources: [clients/new-js/packages/chromadb/README.md:1-50](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/README.md)\n\n## 总结\n\nChroma 的系统架构采用了现代分布式系统的设计理念，通过将前端服务、Worker 节点和协调器分离，实现了系统的可扩展性和高可用性。Arrow 存储格式的应用使得数据操作更加高效，而 gRPC 和 Protocol Buffers 的使用则保证了跨语言的互操作性。\n\n---\n\n\n\n## 数据流与处理流程\n\n### Related Pages\n\nRelated topics: [系统架构](#page-architecture), [查询执行引擎](#page-query-execution)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/blockstore/src/arrow/root.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n- [rust/types/src/collection_schema.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n- [rust/types/src/execution/operator.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/execution/operator.rs)\n- [rust/types/src/topology.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n- [rust/blockstore/src/arrow/block/types.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n- [rust/types/src/metadata.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n- [rust/types/src/sparse_posting_block.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n- [rust/types/src/api_types.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/api_types.rs)\n- [rust/worker/src/compactor/scheduler.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/compactor/scheduler.rs)\n- [rust/blockstore/src/arrow/provider.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n- [rust/index/src/spann/types.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n- [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)\n- [rust/chroma/README.md](https://github.com/chroma-core/chroma/blob/main/rust/chroma/README.md)\n- [rust/wal3/README.md](https://github.com/chroma-core/chroma/blob/main/rust/wal3/README.md)\n \n\n# 数据流与处理流程\n\n## 概述\n\nChroma 是一个开源的 AI 矢量数据库，其核心架构围绕数据存储、索引构建和查询处理三个主要环节构建。数据流与处理流程涵盖从数据摄入到查询响应的完整生命周期，包括数据编码、块存储、索引管理、执行计划生成和多阶段查询处理等关键环节。\n\nChroma 的数据流设计遵循分布式系统原则，支持多租户、多数据库架构，并通过拓扑（Topology）管理跨区域的数据分布。Sources: [rust/types/src/topology.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n\n## 核心架构组件\n\n### 系统层级结构\n\n```mermaid\ngraph TD\n A[API Layer] --> B[Worker Service]\n B --> C[Execution Engine]\n C --> D[Index Layer]\n D --> E[Blockstore]\n E --> F[Arrow Storage]\n \n G[SysDB] --> B\n H[Log Service] --> B\n I[Compactor Scheduler] --> B\n```\n\nChroma 的处理流程涉及多个核心子系统的协作：\n\n| 组件 | 职责 | 主要文件 |\n|------|------|----------|\n| API Layer | 接收请求、参数验证 | rust/types/src/api_types.rs |\n| Worker Service | 任务编排、执行调度 | rust/worker/src/execution/orchestration/mod.rs |\n| Execution Engine | 执行计划、算子处理 | rust/types/src/execution/operator.rs |\n| Index Layer | 矢量索引、HNSW/SPANN | rust/index/src/spann/types.rs |\n| Blockstore | 数据块存储、Arrow IPC | rust/blockstore/src/arrow/provider.rs |\n| Compactor | 压缩合并、垃圾回收 | rust/worker/src/compactor/scheduler.rs |\n\n## 数据摄入流程\n\n### 写入请求处理\n\n客户端通过 API 提交数据写入请求，数据首先经过验证和预处理，然后进入写入流程。Chroma 支持批量写入操作，通过 BlockfileWriter 实现数据的有序或无序写入。 Sources: [rust/blockstore/src/arrow/provider.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n```mermaid\ngraph LR\n A[Add Request] --> B[Validation]\n B --> C[Embedding Generation]\n C --> D[Schema Validation]\n D --> E[BlockfileWriter]\n E --> F[Arrow IPC Format]\n F --> G[Block Storage]\n```\n\n### Blockfile 写入模式\n\nBlockfileWriter 支持两种写入顺序模式：\n\n| 模式 | 说明 | 使用场景 |\n|------|------|----------|\n| Ordered | 有序写入，保证数据顺序 | 需要精确顺序的查询 |\n| Unordered | 无序写入，更高吞吐 | 批量导入、高吞吐写入 |\n\n创建 Blockfile 时可以指定 `fork_from` 参数从现有 Blockfile 分叉，这对于快照和分支操作至关重要。 Sources: [rust/blockstore/src/arrow/provider.rs:50-100](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n## 索引构建与存储\n\n### Schema 与索引配置\n\nChroma 使用 Schema 定义集合的数据结构，支持创建多种类型的索引：\n\n```rust\n// 索引配置示例\nSchema::default()\n .create_index(None, VectorIndexConfig {\n space: Some(Space::Cosine),\n embedding_function: None,\n source_key: None,\n hnsw: None,\n spann: None,\n }.into())?\n .create_index(Some(\"category\"), StringInvertedIndexConfig {}.into())?;\n```\n\nSources: [rust/types/src/collection_schema.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/collection_schema.rs)\n\n### Arrow IPC 存储格式\n\nChroma 使用 Apache Arrow IPC 格式存储数据块，具有以下特点：\n\n- **内存映射支持**：允许高效访问大型数据集\n- **类型安全**：强类型列式存储\n- **跨语言兼容**：可与其他 Arrow 生态工具互操作\n\nBlock 存储包含元数据校验，确保数据完整性：\n\n```rust\npub enum ArrowLayoutVerificationError {\n BufferLengthNotAligned,\n NoRecordBatches,\n MultipleRecordBatches,\n InvalidMessageType,\n RecordBatchDecodeError,\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n### Root 管理与版本控制\n\nRoot 是 Chroma 中的核心存储单元，每个 Root 包含版本信息和块 ID 列表：\n\n```rust\npub(super) fn get_all_block_ids_from_bytes(\n bytes: &[u8],\n id: Uuid,\n) -> Result, FromBytesError> {\n let arrow_reader = arrow::ipc::reader::FileReader::try_new(&mut cursor, None);\n // 版本验证和块 ID 提取\n}\n```\n\nSources: [rust/blockstore/src/arrow/root.rs:1-60](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n## 执行引擎架构\n\n### 执行计划结构\n\nChroma 的查询执行采用算子图模型，每个查询被编译为执行计划：\n\n```mermaid\ngraph TD\n A[Query Input] --> B[Plan Generation]\n B --> C[Operator Tree]\n C --> D[Execution]\n D --> E[Result Assembly]\n E --> F[Response]\n```\n\n执行计划定义了查询的完整执行逻辑，包括过滤、投影、排序等操作。 Sources: [rust/types/src/execution/plan.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/types/src/execution/plan.rs)\n\n### 搜索算子与结果处理\n\n搜索操作返回 `SearchPayloadResult`，包含匹配的记录列表：\n\n```rust\n#[derive(Clone, Debug, Default)]\npub struct SearchPayloadResult {\n pub records: Vec,\n}\n```\n\n每个搜索结果批次还包含日志拉取字节数指标，用于内部性能监控。 Sources: [rust/types/src/execution/operator.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/execution/operator.rs)\n\n## 查询处理流程\n\n### 查询请求结构\n\n```mermaid\nsequenceDiagram\n Client->>API: Query Request\n API->>Validation: Validate Parameters\n Validation->>Execution: Create Execution Plan\n Execution->>Index: Search Index\n Index->>Execution: Merge Results\n Execution->>API: SearchPayloadResult\n API->>Client: Query Response\n```\n\n### Include 列表与响应字段\n\n查询时可以通过 `include` 参数指定返回的字段：\n\n```rust\npub enum Include {\n Distance,\n Document,\n Embedding,\n Metadata,\n Uri,\n}\n\npub struct IncludeList(pub Vec);\n\nimpl IncludeList {\n pub fn default_query() -> Self {\n Self(vec![\n Include::Document,\n Include::Metadata,\n Include::Distance,\n ])\n }\n}\n```\n\nSources: [rust/types/src/api_types.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/types/src/api_types.rs)\n\n### 元数据过滤\n\nChroma 支持丰富的元数据查询操作符：\n\n| 操作符类型 | 说明 | 示例 |\n|-----------|------|------|\n| `Contains` | 文档包含字符串 | `{\"$contains\": \"keyword\"}` |\n| `NotContains` | 文档不包含字符串 | `{\"$not_contains\": \"spam\"}` |\n| `Regex` | 正则表达式匹配 | `{\"$regex\": \"^[A-Z].*\"}` |\n| `NotRegex` | 正则表达式不匹配 | `{\"$not_regex\": \"^test\"}` |\n\nSources: [rust/types/src/metadata.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/metadata.rs)\n\n## 矢量索引系统\n\n### SPANN 索引\n\nSPANN (Scalable PArtitioning Algorithm for Approximate Nearest Neighbor) 是 Chroma 的稀疏矢量索引实现：\n\n```rust\npub struct SpannPosting {\n pub doc_offset_id: u32,\n pub doc_embedding: Vec,\n}\n\npub struct SpannIndexReader<'me> {\n pub posting_lists: BlockfileReader<'me, u32, SpannPostingList<'me>>,\n pub hnsw_index: HnswIndexRef,\n pub versions_map: BlockfileReader<'me, u32, u32>,\n pub dimensionality: usize,\n pub adaptive_search_nprobe: bool,\n}\n```\n\nSources: [rust/index/src/spann/types.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### 稀疏 Posting Block\n\n稀疏索引使用 DirectoryBlock 管理 posting 列表的目录信息：\n\n```text\nbody = [ max_offset: u32 LE, max_weight: f32 LE ] × num_entries\n```\n\n目录块的 `max_weight` 存储维度级别的最大权重，用于早期术语剪枝。 Sources: [rust/types/src/sparse_posting_block.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n\n## 分布式拓扑管理\n\n### ProviderRegion 结构\n\nChroma 使用拓扑管理跨区域的数据分布：\n\n```rust\npub struct ProviderRegion {\n pub name: RegionName,\n pub provider: String, // 如 \"aws\", \"gcp\"\n pub region: String, // 如 \"us-east-1\"\n pub config: T,\n}\n```\n\n每个 ProviderRegion 具有唯一名称，支持云提供商的区域级配置。 Sources: [rust/types/src/topology.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n\n### Topology 结构\n\n```rust\npub struct Topology {\n pub name: TopologyName,\n regions: Vec,\n pub config: T,\n}\n```\n\nTopology 聚合多个 ProviderRegion，支持全局视角的数据分布管理。 Sources: [rust/types/src/topology.rs:80-150](https://github.com/chroma-core/chroma/blob/main/rust/types/src/topology.rs)\n\n## 压缩与后台处理\n\n### Compactor Scheduler\n\nCompactor 负责数据的压缩合并和垃圾回收：\n\n```mermaid\ngraph TD\n A[Scheduler] --> B[Job Queue]\n A --> C[Assignment Policy]\n B --> D[Collections]\n D --> E[Compaction Jobs]\n E --> F[Log Truncation]\n F --> G[Garbage Collection]\n```\n\n核心调度参数：\n\n| 参数 | 说明 |\n|------|------|\n| `max_concurrent_jobs` | 最大并发任务数 |\n| `min_compaction_size` | 最小压缩块大小 |\n| `job_expiry_seconds` | 任务过期时间 |\n| `max_failure_count` | 最大失败重试次数 |\n\nSources: [rust/worker/src/compactor/scheduler.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/compactor/scheduler.rs)\n\n### WAL3 日志系统\n\nChroma 使用 WAL3 (Write-Ahead Log 3) 管理写入日志：\n\n```text\nwal3/\n├── log/Bucket=XXXXX/FragmentSeqNo=XXXXX.parquet\n├── manifest/MANIFEST\n├── snapshot/SNAPSHOT.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n└── garbage/GARBAGE\n```\n\nWAL3 的写入路径：\n\n1. Writer 调用 `push_work` 提交工作到 fragment manager\n2. Fragment manager 批量处理达到阈值时分配 fragment\n3. 数据刷新到对象存储，调用 `assign_timestamp` 更新 manifest\n4. 创建 manifest 变更记录\n\nSources: [rust/wal3/README.md:1-100](https://github.com/chroma-core/chroma/blob/main/rust/wal3/README.md)\n\n## 错误处理机制\n\n### ChromaError trait\n\n所有 Chroma 错误类型实现 `ChromaError` trait：\n\n```rust\npub enum ErrorCodes {\n Internal, // 内部错误\n InvalidArgument, // 参数错误\n NotFound, // 资源未找到\n AlreadyExists, // 资源已存在\n // ... 其他错误码\n}\n```\n\n错误映射示例：\n\n```rust\nmatch self {\n BlockLoadError::IOError(_) => ErrorCodes::Internal,\n BlockLoadError::ArrowError(_) => ErrorCodes::Internal,\n BlockLoadError::NoRecordBatches => ErrorCodes::Internal,\n BlockLoadError::CacheError(_) => ErrorCodes::Internal,\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:80-120](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n## 完整数据流图\n\n```mermaid\ngraph TD\n subgraph Client\n A[HTTP/SDK Request]\n end\n \n subgraph API\n B[Request Validation]\n C[Parameter Parsing]\n end\n \n subgraph Processing\n D[Execution Orchestration]\n E[Plan Generation]\n F[Operator Execution]\n end\n \n subgraph Storage\n G[Blockfile Provider]\n H[Arrow IPC Storage]\n I[WAL3 Log]\n end\n \n subgraph Index\n J[Vector Index HNSW/SPANN]\n K[Inverted Index]\n end\n \n subgraph Background\n L[Compactor Scheduler]\n M[Garbage Collection]\n end\n \n A --> B --> C --> D\n D --> E --> F\n F --> J\n F --> K\n G --> H\n G --> I\n L --> M\n M --> H\n \n F --> N[Query Response]\n```\n\n## 总结\n\nChroma 的数据流与处理流程涵盖从客户端请求到持久化存储的完整链路。核心特点包括：\n\n1. **分层架构**：清晰的 API、执行引擎、存储和索引层分离\n2. **Arrow IPC 格式**：高效、跨语言的列式存储\n3. **多种索引支持**：HNSW 矢量索引、SPANN 稀疏索引、倒排索引\n4. **分布式拓扑**：支持多区域、多租户的数据分布\n5. **后台处理**：压缩调度、垃圾回收保证系统健康\n\nSources: [README.md:1-50](https://github.com/chroma-core/chroma/blob/main/README.md), [rust/chroma/README.md:1-80](https://github.com/chroma-core/chroma/blob/main/rust/chroma/README.md)\n\n---\n\n\n\n## 向量索引系统\n\n### Related Pages\n\nRelated topics: [查询执行引擎](#page-query-execution), [存储系统](#page-storage)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/index/src/hnsw.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/hnsw.rs)\n- [rust/index/src/spann.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann.rs)\n- [rust/index/src/quantization/mod.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/quantization/mod.rs)\n- [rust/index/src/sparse/mod.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/sparse/mod.rs)\n- [rust/segment/src/local_hnsw.rs](https://github.com/chroma-core/chroma/blob/main/rust/segment/src/local_hnsw.rs)\n- [rust/index/src/spann/types.rs](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n- [rust/blockstore/src/arrow/provider.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n \n\n# 向量索引系统\n\n## 概述\n\nChroma的向量索引系统是一个多层次、高性能的近似最近邻（ANN）搜索基础设施，旨在支持大规模向量数据的存储、索引和检索。该系统采用多种索引策略，包括HNSW（分层可导航小世界图）、Spann（稀疏向量索引）、量化（Quantization）以及稀疏索引模块，为不同的搜索场景提供优化的性能和精度平衡。\n\n向量索引系统在Chroma架构中处于核心地位，负责将高维向量数据组织成可高效查询的索引结构，支持余弦距离、点积、欧几里得距离等多种距离函数。\n\nSources: [rust/index/src/hnsw.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/index/src/hnsw.rs)\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"索引层\"\n HNSW[HNSW索引模块]\n Spann[Spann稀疏索引]\n Quantization[量化模块]\n SparseIndex[稀疏索引模块]\n end\n \n subgraph \"存储层\"\n BlockfileProvider[BlockfileProvider]\n BlockfileWriter[BlockfileWriter]\n ArrowOrdered[ArrowOrderedBlockfileWriter]\n ArrowUnordered[ArrowUnorderedBlockfileWriter]\n end\n \n subgraph \"核心组件\"\n HnswIndexProvider[HnswIndexProvider]\n HnswIndexRef[HnswIndexRef]\n SpannIndexReader[SpannIndexReader]\n SpannIndexWriter[SpannIndexWriter]\n end\n \n HNSW --> HnswIndexProvider\n HNSW --> HnswIndexRef\n Spann --> SpannIndexReader\n Spann --> SpannIndexWriter\n BlockfileProvider --> BlockfileWriter\n BlockfileWriter --> ArrowOrdered\n BlockfileWriter --> ArrowUnordered\n HnswIndexProvider --> BlockfileProvider\n```\n\n### 索引类型对比\n\n| 索引类型 | 用途 | 适用场景 | 核心数据结构 |\n|---------|------|---------|-------------|\n| HNSW | 高效ANN搜索 | 稠密向量、精确排序 | 分层图结构 |\n| Spann | 稀疏向量索引 | 稀疏嵌入、混合搜索 | Posting List + HNSW |\n| Quantization | 向量压缩 | 大规模数据、内存受限 | PQ/SQ量化 |\n| Sparse Index | 稀疏特征索引 | 关键词搜索、推荐系统 | 倒排索引 |\n\nSources: [rust/index/src/spann/types.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## HNSW索引模块\n\n### HNSW算法概述\n\nHNSW（Hierarchical Navigable Small World）是一种基于图的近似最近邻搜索算法，通过构建多层可导航小世界图来实现高效搜索。该算法在Chroma中作为默认的向量索引实现，提供了良好的搜索精度和性能平衡。\n\n### HnswIndexProvider\n\n`HnswIndexProvider`是HNSW索引的生命周期管理器，负责索引的创建、打开、关闭和删除操作。\n\n```rust\n// 索引打开操作的核心签名\npub async fn open(\n &self,\n id: &IndexUuid,\n cache_key: &CollectionUuid,\n dimensionality: i32,\n distance_function: DistanceFunction,\n ef_search: usize,\n prefix_path: &str,\n) -> Result\n```\n\nSources: [rust/index/src/spann/types.rs:45-65](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### 关键配置参数\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| dimensionality | i32 | 向量维度 | 必填 |\n| distance_function | DistanceFunction | 距离函数 | 必填 |\n| ef_search | usize | 搜索时的候选集大小 | 可配置 |\n| prefix_path | &str | 存储路径前缀 | 必填 |\n\n### HnswIndexRef结构\n\n`HnswIndexRef`是对HNSW索引的引用类型，用于在查询阶段访问索引数据。它持有索引的所有权引用，确保索引在查询期间保持有效。\n\nSources: [rust/index/src/spann/types.rs:50](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## Spann稀疏向量索引\n\n### Spann架构\n\nSpann是Chroma专为稀疏向量设计的混合索引系统，结合了倒排索引和HNSW图的优点。它由三个核心组件构成：\n\n```mermaid\ngraph LR\n subgraph \"SpannIndex\"\n PostingList[Posting Lists]\n HNSWGraph[HNSW Graph]\n VersionsMap[Versions Map]\n end\n \n subgraph \"数据结构\"\n SpannPosting[SpannPosting
doc_offset_id
doc_embedding]\n SpannPostingList[SpannPostingList]\n end\n \n PostingList --> SpannPostingList\n HNSWGraph --> HnswIndexRef\n```\n\n### SpannPosting结构\n\n```rust\n#[derive(Debug)]\npub struct SpannPosting {\n pub doc_offset_id: u32, // 文档偏移ID\n pub doc_embedding: Vec, // 文档向量\n}\n```\n\nSources: [rust/index/src/spann/types.rs:38-42](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### SpannIndexReader\n\n`SpannIndexReader`提供对Spann索引的只读访问，包含以下核心字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| posting_lists | BlockfileReader | Posting列表读取器 |\n| hnsw_index | HnswIndexRef | HNSW图索引引用 |\n| versions_map | BlockfileReader | 版本映射 |\n| dimensionality | usize | 向量维度 |\n| adaptive_search_nprobe | bool | 自适应搜索开关 |\n| params | InternalSpannConfiguration | 内部配置参数 |\n\nSources: [rust/index/src/spann/types.rs:44-54](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### SpannIndexWriter\n\n`SpannIndexWriter`负责Spann索引的写入操作，核心创建方法签名：\n\n```rust\npub async fn from_id(\n hnsw_provider: &HnswIndexProvider,\n hnsw_id: Option<&IndexUuid>,\n versions_map_id: Option<&Uuid>,\n posting_list_id: Option<&Uuid>,\n max_head_id_bf_id: Option<&Uuid>,\n collection_id: &CollectionUuid,\n prefix_path: &str,\n dimensionality: usize,\n blockfile_provider: &BlockfileProvider,\n params: InternalSpannConfiguration,\n gc_context: GarbageCollectionContext,\n pl_block_size: usize,\n metrics: SpannMetrics,\n cmek: Option,\n) -> Result\n```\n\nSources: [rust/index/src/spann/types.rs:80-130](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### SpannPostingList管理\n\nSpann索引使用Blockfile来存储Posting List，支持高效的序列化和反序列化：\n\n```rust\npub async fn create_postings_list_writer(\n blockfile_provider: &BlockfileProvider,\n prefix_path: &str,\n pl_block_size: usize,\n cmek: Option,\n) -> Result\n```\n\n写入时支持配置最大块大小和CMEK（客户托管密钥）加密选项。\n\nSources: [rust/index/src/spann.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann.rs)\n\n## 量化模块（Quantization）\n\n### 量化概述\n\n量化模块提供了向量压缩功能，通过将高精度浮点向量转换为低精度的表示形式，显著减少存储空间和内存占用，同时尽可能保持搜索精度。\n\n### 量化配置\n\n| 配置项 | 说明 |\n|--------|------|\n| QuantizationType | 量化类型（PQR/SQ等） |\n| BucketCount | 量化桶数量 |\n| CodeWidth | 编码宽度 |\n| DistanceTable | 距离查表 |\n\nSources: [rust/index/src/quantization/mod.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/index/src/quantization/mod.rs)\n\n### 量化流程\n\n```mermaid\ngraph LR\n A[原始向量] --> B[训练量化器]\n B --> C[计算码本]\n C --> D[编码向量]\n D --> E[存储压缩向量]\n E --> F[查询时解码]\n F --> G[计算距离]\n```\n\n## 稀疏索引模块\n\n### 稀疏索引设计\n\n稀疏索引专门处理稀疏特征向量，典型应用于关键词匹配、推荐系统和混合搜索场景。\n\n### DirectoryBlock结构\n\n稀疏索引使用DirectoryBlock来组织posting blocks：\n\n```rust\npub struct DirectoryBlock(SparsePostingBlock);\n\nimpl DirectoryBlock {\n pub fn new(\n max_offsets: &[u32], // 每个posting block的最大偏移\n max_weights: &[f32], // 每个posting block的最大权重\n ) -> Result\n}\n```\n\nDirectoryBlock的二进制布局：\n- **Header**: magic bytes + block count + dimension-level max weight\n- **Body**: `[max_offset: u32 LE, max_weight: f32 LE] × num_entries`\n\nSources: [rust/types/src/sparse_posting_block.rs:1-60](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n\n### 稀疏索引错误处理\n\n| 错误类型 | 说明 |\n|---------|------|\n| MismatchedLengths | 偏移数组和权重数组长度不匹配 |\n| TooManyEntries | 条目数量超过u16::MAX限制 |\n\nSources: [rust/types/src/sparse_posting_block.rs:30-45](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n\n## Blockfile存储层\n\n### BlockfileProvider架构\n\nBlockfile是Chroma的底层存储抽象，封装了Arrow IPC格式的持久化存储。\n\n```mermaid\ngraph TD\n BlockfileProvider --> ArrowOrderedBlockfileWriter\n BlockfileProvider --> ArrowUnorderedBlockfileWriter\n BlockfileProvider --> BlockfileReader\n \n ArrowOrderedBlockfileWriter[\"ArrowOrderedBlockfileWriter
顺序写入\"]\n ArrowUnorderedBlockfileWriter[\"ArrowUnorderedBlockfileWriter
无序写入\"]\n \n BlockfileWriterOptions --> BlockfileProvider\n```\n\nSources: [rust/blockstore/src/arrow/provider.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n### 写入模式\n\n| 模式 | 说明 | 使用场景 |\n|------|------|---------|\n| Ordered | 顺序写入，保证追加顺序 | 日志、事务性数据 |\n| Unordered | 无序写入，批量优化 | 批量导入、重建索引 |\n\n### Fork操作\n\nBlockfile支持从现有blockfile创建分支（fork），用于创建索引快照或从检查点恢复：\n\n```rust\npub async fn fork(\n &self,\n fork_from: &Uuid,\n new_id: Uuid,\n prefix_path: &Path,\n max_block_size_bytes: usize,\n) -> Result>\n```\n\nSources: [rust/blockstore/src/arrow/provider.rs:30-60](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n### 块大小配置\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| max_block_size_bytes | 单个数据块的最大字节数 | BlockManager默认值 |\n\n## 距离函数\n\n系统支持多种距离函数，用于计算向量相似度：\n\n| 距离函数 | 说明 | 适用场景 |\n|---------|------|---------|\n| Cosine | 余弦距离 | 归一化向量 |\n| Dot | 点积 | 未归一化向量 |\n| L2 | 欧几里得距离 | 几何距离 |\n| IP | 内积 | 相似度排序 |\n\nSources: [rust/index/src/spann/types.rs:60](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## 错误处理\n\n### 索引错误类型\n\n| 错误类型 | 错误码 | 说明 |\n|---------|--------|------|\n| VersionsMapNotFound | NotFound | 版本映射不存在 |\n| ScanHnswError | Internal | HNSW扫描错误 |\n| DataInconsistencyError | Internal | 数据不一致 |\n| RngError | Internal | 随机数生成器错误 |\n\nSources: [rust/index/src/spann/types.rs:20-30](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## 索引生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: 创建索引\n Created --> Open: 打开索引\n Open --> Query: 执行查询\n Open --> Write: 写入数据\n Write --> Open: 写入完成\n Query --> Open: 查询完成\n Open --> Close: 关闭索引\n Close --> [*]: 资源释放\n Open --> Compact: 压缩合并\n Compact --> Open: 压缩完成\n```\n\n## 性能优化配置\n\n### HNSW搜索参数\n\n| 参数 | 说明 | 建议值 |\n|------|------|--------|\n| ef_search | 搜索时访问的最近邻候选数 | 100-500 |\n| ef_construction | 构建时使用的候选数 | 100-200 |\n| m | 每层连接数 | 16-64 |\n\n### 自适应搜索\n\nSpann索引支持`adaptive_search_nprobe`参数，启用时系统会根据查询结果动态调整搜索范围，在精度和性能之间自动平衡。\n\n## 总结\n\nChroma的向量索引系统通过模块化设计，提供了一套完整的高性能向量搜索解决方案：\n\n1. **HNSW模块**提供基础的ANN搜索能力\n2. **Spann模块**专门优化稀疏向量处理\n3. **量化模块**支持大规模数据的压缩存储\n4. **稀疏索引模块**处理高维稀疏特征\n5. **Blockfile存储层**确保数据持久化和高效读取\n\n这套系统在保证搜索精度的同时，通过多种优化策略实现了存储效率和查询性能的平衡，满足从原型开发到生产部署的各种场景需求。\n\n---\n\n\n\n## 查询执行引擎\n\n### Related Pages\n\nRelated topics: [向量索引系统](#page-vector-index), [Python客户端](#page-python-client)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/system/src/execution/operator.rs](https://github.com/chroma-core/chroma/blob/main/rust/system/src/execution/operator.rs)\n- [rust/types/src/execution/operator.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/execution/operator.rs)\n- [rust/worker/src/execution/operators/knn_hnsw.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/knn_hnsw.rs)\n- [rust/worker/src/execution/operators/filter.rs](https://github.com/chroma-core/chroma/blob/main/rust/worker/src/execution/operators/filter.rs)\n- [rust/execution/expression/plan.py](https://github.com/chroma-core/chroma/blob/main/rust/execution/expression/plan.py)\n \n\n# 查询执行引擎\n\n## 概述\n\nChroma 的查询执行引擎是系统的核心组件，负责处理向量搜索、元数据过滤和文档查询等操作。该引擎采用算子（Operator）模式设计，将复杂的查询流程分解为可组合的执行单元，支持灵活的查询规划和高效的结果处理。\n\n查询执行引擎的主要职责包括：\n\n- **向量最近邻搜索**：通过 HNSW 等索引实现高效的向量相似度搜索\n- **元数据过滤**：支持标量值和数组类型的元数据条件过滤\n- **文档全文搜索**：支持文档内容的包含和非包含查询\n- **结果聚合**：整合来自多个数据段的搜索结果\n\nSources: [rust/types/src/execution/operator.rs:1-50]()\n\n## 架构设计\n\n### 核心组件\n\n查询执行引擎由以下核心组件构成：\n\n| 组件 | 职责 | 位置 |\n|------|------|------|\n| 算子接口 (Operator Trait) | 定义算子的通用行为和错误处理 | rust/system/src/execution/operator.rs |\n| 类型定义 | 定义搜索结果、记录等数据结构 | rust/types/src/execution/operator.rs |\n| KNN 算子 | 实现基于 HNSW 的向量搜索 | rust/worker/src/execution/operators/knn_hnsw.rs |\n| 过滤算子 | 处理元数据和文档过滤条件 | rust/worker/src/execution/operators/filter.rs |\n| 执行计划 | Python 层的查询规划 | rust/execution/expression/plan.py |\n\n### 数据流架构\n\n```mermaid\ngraph TD\n A[查询请求] --> B[执行计划解析]\n B --> C[过滤算子 Filter]\n C --> D[KNN 算子 HNSW]\n D --> E[结果聚合]\n E --> F[SearchPayloadResult]\n F --> G[返回结果]\n \n C -.->|预过滤| H[元数据索引]\n D -.->|向量搜索| I[HNSW 索引]\n \n H --> J[Blockfile]\n I --> J\n```\n\nSources: [rust/execution/expression/plan.py:1-100]()\n\n## 算子接口设计\n\n### Operator Trait\n\n查询执行引擎中的所有算子都实现统一的 `Operator` 接口。该接口定义了算子的通用行为：\n\n```rust\n// 伪代码表示结构\npub trait Operator {\n type Error: ChromaError;\n \n async fn execute(&self, input: Input) -> Result;\n}\n```\n\n所有算子都需要实现 `ChromaError` trait，提供错误码映射和追踪配置：\n\n```rust\nimpl ChromaError for OperatorError {\n fn code(&self) -> ErrorCodes {\n match self {\n Self::Internal(_) => ErrorCodes::Internal,\n Self::InvalidArgument(_) => ErrorCodes::InvalidArgument,\n }\n }\n \n fn should_trace_error(&self) -> bool {\n true\n }\n}\n```\n\nSources: [rust/system/src/execution/operator.rs:1-80]()\n\n## 数据结构\n\n### 搜索结果类型\n\n查询执行引擎使用以下核心数据结构：\n\n#### SearchPayloadResult\n\n单次搜索的有效载荷结果：\n\n```rust\n#[derive(Clone, Debug, Default)]\npub struct SearchPayloadResult {\n pub records: Vec,\n}\n```\n\n包含搜索匹配的记录列表，每条记录包含向量、文档和元数据信息。\n\n#### SearchResult\n\n批量搜索操作的结果：\n\n```rust\n/// Results from a batch search operation.\n/// \n/// Contains results for each search payload in the batch, maintaining the same order\n/// as the input searches.\npub struct SearchResult {\n pub results: Vec,\n pub pulled_log_bytes: u64, // 内部指标：日志拉取字节数\n}\n```\n\nSources: [rust/types/src/execution/operator.rs:1-60]()\n\n### Where 过滤条件\n\n支持多种过滤条件的 `Where` 枚举类型：\n\n| 变体 | 描述 | 示例 |\n|------|------|------|\n| `Direct(value)` | 直接比较 | `id == \"xxx\"` |\n| `Key(metadata)` | 元数据字段比较 | `metadata.age > 21` |\n| `Document(expr)` | 文档内容匹配 | `contains(\"keyword\")` |\n| `And(left, right)` | 逻辑与 | `age > 18 AND active == true` |\n| `Or(left, right)` | 逻辑或 | `tag == \"A\" OR tag == \"B\"` |\n\n#### 文档操作符\n\n```rust\n#[derive(Clone, Debug, PartialEq)]\npub enum DocumentOperator {\n Contains, // 包含\n NotContains, // 不包含\n Regex, // 正则匹配\n NotRegex, // 正则不匹配\n}\n```\n\nSources: [rust/types/src/metadata.rs:1-50]()\n\n## 核心算子实现\n\n### KNN HNSW 算子\n\nKNN（K-Nearest Neighbors）算子使用 HNSW（Hierarchical Navigable Small World）算法实现高效的向量相似度搜索。\n\n#### 工作流程\n\n```mermaid\ngraph LR\n A[查询向量] --> B[HNSW 图遍历]\n B --> C[候选集合]\n C --> D[距离计算]\n D --> E[Top-K 结果]\n E --> F[结果包装]\n```\n\n#### 配置参数\n\n| 参数 | 类型 | 描述 | 默认值 |\n|------|------|------|--------|\n| `ef_search` | usize | 搜索时的动态列表大小 | 100 |\n| `k` | usize | 返回的最近邻数量 | 10 |\n| `distance_function` | DistanceFunction | 距离度量函数 | Cosine |\n| `dimensionality` | usize | 向量维度 | - |\n\n#### 关键方法\n\n```rust\nimpl<'me> SpannIndexReader<'me> {\n async fn hnsw_index_from_id(\n hnsw_provider: &HnswIndexProvider,\n id: &IndexUuid,\n cache_key: &CollectionUuid,\n distance_function: DistanceFunction,\n dimensionality: usize,\n ef_search: usize,\n prefix_path: &str,\n ) -> Result\n}\n```\n\nSources: [rust/worker/src/execution/operators/knn_hnsw.rs:1-80]()\n\n### 过滤算子\n\n过滤算子负责处理元数据和文档内容的条件过滤。\n\n#### 过滤类型\n\n| 过滤类型 | 处理对象 | 支持操作符 |\n|----------|----------|------------|\n| MetadataScalar | 标量元数据 | `=`, `!=`, `>`, `<`, `>=`, `<=`, `And`, `Or` |\n| MetadataArray | 数组元数据 | `contains_value`, `not_contains_value` |\n| Document | 文档全文 | `contains`, `not_contains`, `regex`, `not_regex` |\n\n#### Key 构建器\n\n`Key` 类型提供了流式 API 来构建过滤条件：\n\n```rust\n// 元数据标量过滤\nlet filter = Key::field(\"age\").gte(21);\nlet filter = Key::field(\"category\").eq(\"books\");\n\n// 元数据数组包含\nlet filter = Key::field(\"tags\").contains_value(\"action\");\n\n// 文档全文搜索\nlet filter = Key::Document.contains(\"machine learning\");\nlet filter = Key::Document.not_contains(\"deprecated\");\n```\n\nSources: [rust/worker/src/execution/operators/filter.rs:1-60]()\nSources: [rust/types/src/execution/operator.rs:80-150]()\n\n## 执行计划\n\n### Python 层规划\n\n在 Python 层，执行计划将用户查询转换为可执行的算子序列：\n\n```python\n# rust/execution/expression/plan.py\nclass ExecutionPlan:\n def __init__(self, collection):\n self.collection = collection\n self.operators = []\n \n def add_filter(self, where):\n # 添加过滤算子\n pass\n \n def add_knn(self, query_embedding, k):\n # 添加 KNN 搜索算子\n pass\n```\n\n### 查询转换流程\n\n```mermaid\ngraph TD\n A[Python API Query] --> B[WhereClause 解析]\n B --> C[ExecutionPlan 构建]\n C --> D[算子序列生成]\n D --> E[Rust 执行]\n E --> F[Protobuf 序列化]\n F --> G[结果返回]\n```\n\nSources: [rust/execution/expression/plan.py:1-100]()\n\n## 错误处理\n\n### 错误码映射\n\n| 错误类型 | ErrorCode | 说明 |\n|----------|-----------|------|\n| IOError | Internal | 输入输出错误 |\n| ArrowError | Internal | Arrow 格式错误 |\n| ArrowLayoutVerificationError | Internal | Arrow 布局验证失败 |\n| NoRecordBatches | Internal | IPC 文件无记录批次 |\n| BlockToBytesError | Internal | 块序列化错误 |\n| CacheError | Internal | 缓存操作错误 |\n\n### 错误处理实现\n\n```rust\nimpl ChromaError for BlockLoadError {\n fn code(&self) -> ErrorCodes {\n match self {\n BlockLoadError::IOError(_) => ErrorCodes::Internal,\n BlockLoadError::ArrowError(_) => ErrorCodes::Internal,\n BlockLoadError::ArrowLayoutVerificationError(_) => ErrorCodes::Internal,\n BlockLoadError::NoRecordBatches => ErrorCodes::Internal,\n BlockLoadError::BlockToBytesError(_) => ErrorCodes::Internal,\n BlockLoadError::CacheError(_) => ErrorCodes::Internal,\n }\n }\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:1-50]()\n\n## 性能优化\n\n### 索引结构\n\nChroma 使用多级索引结构优化查询性能：\n\n1. **Blockfile**：底层存储，支持高效的块读写\n2. **HNSW 索引**：向量搜索的核心，提供对数级搜索复杂度\n3. **Sparse Index**：稀疏向量索引，用于高效的范围查询\n\n### 执行策略\n\n| 策略 | 适用场景 | 优势 |\n|------|----------|------|\n| 预过滤 | 过滤条件较严格 | 减少搜索空间 |\n| 后过滤 | 过滤条件较宽松 | 提高搜索并行度 |\n| 混合过滤 | 复杂查询 | 平衡精度和性能 |\n\n### 缓存机制\n\n执行引擎利用多层缓存提升性能：\n\n- **HNSW 索引缓存**：避免重复加载索引\n- **块缓存**：减少磁盘 IO\n- **查询结果缓存**：加速重复查询\n\n## 扩展性\n\n### 自定义算子\n\n系统支持通过实现 `Operator` trait 添加自定义算子：\n\n```rust\npub trait Operator {\n type Error: ChromaError;\n \n async fn execute(&self, input: Input) -> Result;\n}\n```\n\n### 算子组合\n\n通过算子的可组合性，可以构建复杂的查询管道：\n\n```mermaid\ngraph LR\n A[Query] --> B[Filter1]\n B --> C[Filter2]\n C --> D[KNNSearch]\n D --> E[Rank]\n E --> F[Project]\n F --> G[Result]\n```\n\n## 总结\n\nChroma 的查询执行引擎通过算子模式和分层架构，实现了高效、灵活的查询处理能力。核心设计特点包括：\n\n- **统一的算子接口**：简化了算子的实现和组合\n- **多级索引支持**：HNSW + Blockfile 提供高效的向量和标量查询\n- **灵活的结果聚合**：支持批量搜索和结果合并\n- **完善的错误处理**：提供细粒度的错误码和追踪机制\n\n这一架构使得 Chroma 能够高效处理大规模向量数据和复杂的查询条件，同时保持良好的可扩展性。\n\n---\n\n\n\n## Python客户端\n\n### Related Pages\n\nRelated topics: [JavaScript/TypeScript客户端](#page-javascript-client), [嵌入函数集成](#page-embedding-functions)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [chromadb/api/client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/client.py)\n- [chromadb/api/async_client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/async_client.py)\n- [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)\n- [chromadb/api/models/AsyncCollection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/AsyncCollection.py)\n- [chromadb/api/fastapi.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/fastapi.py)\n \n\n# Python客户端\n\n## 概述\n\nChroma的Python客户端是官方提供的Python SDK，为开发者提供了与Chroma向量数据库交互的完整接口。该客户端支持两种运行模式：嵌入式模式（Embedded Mode）和客户端-服务器模式（Client-Server Mode），满足不同场景下的使用需求。\n\nPython客户端的核心API仅包含四个主要函数，通过简洁的接口封装了文档管理、向量嵌入、相似度搜索等核心功能。Sources: [README.md]()\n\n## 架构设计\n\n### 整体架构\n\nChroma Python客户端采用分层架构设计，主要包含以下核心组件：\n\n```mermaid\ngraph TD\n A[Python Client] --> B[Sync Client]\n A --> C[Async Client]\n B --> D[Collection]\n C --> E[AsyncCollection]\n D --> F[Embedding Functions]\n E --> F\n B --> G[FastAPI Client]\n C --> G\n G --> H[Chroma Server]\n```\n\n### 客户端类型\n\n| 客户端类型 | 文件位置 | 用途 | 适用场景 |\n|-----------|---------|------|---------|\n| `Client` | `chromadb/api/client.py` | 同步客户端 | 标准Python应用 |\n| `AsyncClient` | `chromadb/api/async_client.py` | 异步客户端 | 异步Web框架、高并发应用 |\n| `FastAPI` | `chromadb/api/fastapi.py` | 服务器端API | Chroma服务器部署 |\n\nSources: [chromadb/api/client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/client.py), [chromadb/api/async_client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/async_client.py), [chromadb/api/fastapi.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/fastapi.py)()\n\n## 同步客户端\n\n### 初始化与配置\n\n同步客户端通过`chromadb.Client()`方法创建，支持嵌入式内存模式和持久化存储模式。\n\n```python\nimport chromadb\n\n# 嵌入式内存模式（临时数据）\nclient = chromadb.Client()\n\n# 带持久化的嵌入式模式\nclient = chromadb.PersistentClient(path=\"/path/to/chroma_db\")\n```\n\n### 核心功能\n\n**Collection管理**\n\nCollection是Chroma中组织文档和向量数据的基本单元。客户端提供了完整的Collection操作接口：\n\n```python\n# 创建Collection\ncollection = client.create_collection(\n name=\"my-documents\",\n metadata={\"description\": \"文档集合\"}\n)\n\n# 获取已存在的Collection\ncollection = client.get_collection(name=\"my-documents\")\n\n# 获取或创建Collection\ncollection = client.get_or_create_collection(name=\"my-documents\")\n\n# 列出所有Collection\ncollections = client.list_collections()\n\n# 删除Collection\nclient.delete_collection(name=\"my-documents\")\n```\n\nSources: [chromadb/api/client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/client.py), [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)()\n\n## 异步客户端\n\n### 异步支持\n\n`AsyncClient`提供了完全异步的操作接口，适用于`asyncio`环境和异步Web框架（如FastAPI）。\n\n```python\nimport chromadb\n\n# 创建异步客户端\nclient = chromadb.AsyncClient()\n\n# 异步创建Collection\ncollection = await client.create_collection(name=\"async-collection\")\n```\n\n### 性能优势\n\n| 特性 | 同步客户端 | 异步客户端 |\n|-----|-----------|-----------|\n| 并发处理 | 单线程阻塞 | 多任务并发 |\n| 适用框架 | Django, Flask | FastAPI, aiohttp |\n| 连接复用 | 每次请求新建 | 长连接复用 |\n| 内存占用 | 较低 | 略高 |\n\nSources: [chromadb/api/async_client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/async_client.py), [chromadb/api/models/AsyncCollection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/AsyncCollection.py)()\n\n## Collection操作\n\n### 数据模型\n\nCollection支持存储以下类型的数据：\n\n```python\ncollection.add(\n documents=[\"文档内容1\", \"文档内容2\"], # 文档文本\n metadatas=[{\"source\": \"doc1\"}, {\"source\": \"doc2\"}], # 元数据\n ids=[\"id1\", \"id2\"], # 唯一标识符\n embeddings=[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] # 可选：自定义向量\n)\n```\n\n### 插入操作\n\n| 参数 | 类型 | 必需 | 说明 |\n|-----|------|-----|------|\n| `ids` | List[str] | 是 | 文档唯一标识符 |\n| `documents` | List[str] | 否 | 文档内容文本 |\n| `embeddings` | List[List[float]] | 否 | 向量嵌入 |\n| `metadatas` | List[dict] | 否 | 元数据字典 |\n\nSources: [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)()\n\n### 查询操作\n\n```python\n# 基于文本的相似度查询\nresults = collection.query(\n query_texts=[\"查询文本\"],\n n_results=2, # 返回2个最相似结果\n where={\"source\": \"doc1\"}, # 元数据过滤\n where_document={\"$contains\": \"关键词\"} # 文档内容过滤\n)\n\n# 基于向量的查询\nresults = collection.query(\n query_embeddings=[[1.0, 2.0, 3.0]],\n n_results=2\n)\n```\n\n### 条件过滤\n\nChroma支持强大的条件过滤功能：\n\n```python\n# 元数据过滤\ncollection.query(\n query_texts=[\"查询\"],\n where={\"metadata_field\": \"value\"}\n)\n\n# 文档内容过滤\ncollection.query(\n query_texts=[\"查询\"],\n where_document={\"$contains\": \"搜索字符串\"}\n)\n```\n\nSources: [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)()\n\n## Embedding函数\n\n### 嵌入函数架构\n\n```mermaid\ngraph LR\n A[Input Text] --> B[Embedding Function]\n B --> C[Vector Embedding]\n C --> D[Storage/Indexing]\n```\n\n### 内置嵌入函数\n\nChroma Python客户端支持多种嵌入函数提供商：\n\n| 提供商 | 包名 | 默认模型 |\n|-------|------|---------|\n| OpenAI | `chromadb.utils.embedding_functions` | text-embedding-ada-002 |\n| Cohere | `chromadb.utils.embedding_functions` | embed-english-v3.0 |\n| Hugging Face | `chromadb.utils.embedding_functions` | sentence-transformers |\n| Ollama | `chromadb.utils.embedding_functions` | 自定义模型 |\n\n### 自定义嵌入函数\n\n```python\nfrom chromadb.utils.embedding_functions import OpenAIEmbeddingFunction\n\nembedder = OpenAIEmbeddingFunction(\n api_key=\"your-api-key\",\n model_name=\"text-embedding-3-small\"\n)\n\ncollection = client.create_collection(\n name=\"my-collection\",\n embedding_function=embedder\n)\n```\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)()\n\n## 使用模式\n\n### 嵌入式模式\n\n适用于本地开发和测试，数据存储在内存或本地文件系统：\n\n```python\nimport chromadb\n\n# 内存模式\nclient = chromadb.Client()\n\n# 本地持久化模式\nclient = chromadb.PersistentClient(path=\"./chroma_db\")\n```\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)()\n\n### 客户端-服务器模式\n\n适用于生产环境和分布式部署：\n\n```bash\n# 启动Chroma服务器\nchroma run --path /chroma_db_path --host 0.0.0.0 --port 8000\n```\n\n```python\nimport chromadb\n\n# 连接远程服务器\nclient = chromadb.Client(\n settings=Settings(\n chroma_api_impl=\"rest\",\n persist_directory=\"http://localhost:8000\"\n )\n)\n```\n\nSources: [README.md](https://github.com/chroma-core/chroma/blob/main/README.md)()\n\n## API参考\n\n### 客户端方法\n\n#### `chromadb.Client()`\n\n创建Chroma客户端实例。\n\n#### `client.create_collection(name, metadata, embedding_function)`\n\n创建新的Collection。\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| `name` | str | Collection名称 |\n| `metadata` | dict | Collection元数据 |\n| `embedding_function` | function | 嵌入函数 |\n\n#### `client.get_collection(name)`\n\n获取指定名称的Collection。\n\n#### `client.list_collections()`\n\n返回所有Collection列表。\n\n#### `client.delete_collection(name)`\n\n删除指定Collection。\n\n### Collection方法\n\n| 方法 | 说明 |\n|-----|------|\n| `add()` | 添加文档 |\n| `get()` | 获取文档 |\n| `update()` | 更新文档 |\n| `upsert()` | 插入或更新 |\n| `delete()` | 删除文档 |\n| `query()` | 相似度查询 |\n| `peek()` | 查看前N条记录 |\n| `count()` | 统计文档数量 |\n| `modify()` | 修改Collection元数据 |\n\nSources: [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py)()\n\n## 最佳实践\n\n### 性能优化\n\n1. **批量操作**：尽量使用批量添加而非单条添加\n2. **嵌入函数复用**：创建Collection时指定嵌入函数，避免重复初始化\n3. **索引优化**：合理设置`hnsw:space`参数选择合适的距离度量\n\n### 数据组织\n\n1. **合理的Collection划分**：按主题或数据类型分离Collection\n2. **元数据设计**：元数据用于过滤，应设计清晰的元数据结构\n3. **ID管理**：使用有意义的ID便于数据追踪\n\n### 错误处理\n\n```python\ntry:\n collection = client.get_collection(name=\"non-existent\")\nexcept Exception as e:\n print(f\"Error: {e}\")\n```\n\n## 总结\n\nChroma Python客户端提供了简洁而强大的接口来管理向量数据。通过同步和异步两种客户端类型，配合灵活的Collection管理和丰富的嵌入函数支持，开发者可以快速构建基于向量检索的AI应用。Sources: [chromadb/api/client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/client.py), [chromadb/api/async_client.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/async_client.py), [chromadb/api/models/Collection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/Collection.py), [chromadb/api/models/AsyncCollection.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/models/AsyncCollection.py), [chromadb/api/fastapi.py](https://github.com/chroma-core/chroma/blob/main/chromadb/api/fastapi.py)()\n\n---\n\n\n\n## JavaScript/TypeScript客户端\n\n### Related Pages\n\nRelated topics: [Python客户端](#page-python-client)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [clients/js/packages/chromadb-core/src/ChromaClient.ts](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-core/src/ChromaClient.ts)\n- [clients/new-js/packages/chromadb/src/chroma-client.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/src/chroma-client.ts)\n- [clients/new-js/packages/chromadb/src/api/client.gen.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/src/api/client.gen.ts)\n- [clients/js/packages/chromadb-client/src/index.ts](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-client/src/index.ts)\n- [clients/new-js/packages/chromadb/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/package.json)\n- [clients/js/packages/chromadb/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb/package.json)\n- [clients/js/packages/chromadb-client/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-client/package.json)\n- [clients/js/packages/chromadb-core/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-core/package.json)\n- [clients/new-js/packages/ai-embeddings/all/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/all/package.json)\n- [clients/new-js/packages/ai-embeddings/common/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/common/package.json)\n \n\n# JavaScript/TypeScript客户端\n\nChromaDB JavaScript/TypeScript客户端是Chroma向量数据库的官方前端SDK，支持Node.js环境和现代浏览器。该客户端提供了与Chroma服务器端进行通信的完整接口，包括集合管理、向量存储、相似性查询等功能。\n\n## 架构概述\n\nChromaDB JavaScript客户端存在两套主要实现，分别位于不同的代码目录中：\n\n### 客户端版本对比\n\n| 特性 | 新版客户端 (`new-js`) | 旧版客户端 (`js`) |\n|------|---------------------|------------------|\n| 版本号 | 3.4.5 | 2.4.7 |\n| 模块格式 | ESM优先，支持CJS | 同时支持ESM和CJS |\n| 嵌入函数 | 通过独立包提供 | 内置或作为peerDependencies |\n| 构建工具 | tsup | tsup |\n| API风格 | 现代化Promise/Async | 兼容旧版 |\n\n### 代码结构\n\n```mermaid\ngraph TD\n subgraph \"clients/new-js\"\n A[new-js/chromadb] --> B[new-js/ai-embeddings]\n B --> C[各嵌入提供者包]\n C --> D[TogetherAI]\n C --> E[GoogleGemini]\n C --> F[Jina]\n C --> G[VoyageAI]\n C --> H[SentenceTransformer]\n C --> I[BM25]\n end\n \n subgraph \"clients/js\"\n J[chromadb-core] --> K[chromadb-embedded]\n J --> L[chromadb-client]\n end\n \n M[Chroma Server] <--> N[HTTP API]\n A --> N\n J --> N\n K --> M\n```\n\n## 核心组件\n\n### 1. ChromaClient (新版)\n\n新版客户端的核心类位于 `clients/new-js/packages/chromadb/src/chroma-client.ts`，提供了与Chroma服务器通信的主要接口。\n\n**主要功能：**\n\n- 创建和管理集合\n- 执行向量查询操作\n- 管理集合元数据\n- 处理身份验证（可选）\n\n**基本用法：**\n\n```typescript\nimport { ChromaClient } from 'chromadb';\n\nconst client = new ChromaClient({\n path: 'http://localhost:8000',\n});\n\nconst collection = await client.createCollection({\n name: 'my-collection',\n embeddingFunction: embedder, // 可选自定义嵌入函数\n metadata: { 'description': '我的第一个集合' }\n});\n```\n\nSources: [clients/new-js/packages/chromadb/src/chroma-client.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/src/chroma-client.ts)\n\n### 2. ChromaClient (旧版)\n\n旧版客户端位于 `clients/js/packages/chromadb-core/src/ChromaClient.ts`，功能类似但API略有不同。\n\n**包结构对比：**\n\n| 包名 | 说明 | 嵌入函数 |\n|------|------|---------|\n| `chromadb` | 完整包，内置所有嵌入库 | 已包含 |\n| `chromadb-client` | 仅客户端，嵌入为peerDependencies | 需单独安装 |\n\nSources: [clients/js/packages/chromadb-core/src/ChromaClient.ts](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-core/src/ChromaClient.ts)\n\n### 3. Collection操作\n\n集合是Chroma中组织向量数据的基本单位。以下是Collection的主要操作：\n\n```typescript\n// 添加文档\nawait collection.add({\n ids: ['1', '2', '3'],\n documents: ['第一个文档', '第二个文档', '第三个文档'],\n metadatas: [{ source: 'a' }, { source: 'b' }, { source: 'c' }],\n});\n\n// 查询相似文档\nconst results = await collection.query({\n queryTexts: ['查询文本'],\n nResults: 2,\n});\n\n// 获取数据\nconst data = await collection.get({\n ids: ['1', '2'],\n where: { source: 'a' },\n});\n\n// 删除数据\nawait collection.delete({\n where: { source: 'b' },\n});\n```\n\n## 嵌入函数系统\n\nChroma使用嵌入函数(Embedding Function)将文本转换为向量。新版客户端通过独立包提供各种嵌入提供者。\n\n### 支持的嵌入提供者\n\n| 提供者 | 包名 | 模型默认 |\n|--------|------|---------|\n| Together AI | `@chroma-core/together-ai` | togethercomputer/m2-bert-80M-8k-retrieval |\n| Google Gemini | `@chroma-core/google-gemini` | text-embedding-004 |\n| Jina AI | `@chroma-core/jina` | jina-embeddings-v2-base-en |\n| Voyage AI | `@chroma-core/voyageai` | voyage-2 |\n| HuggingFace | `@chroma-core/huggingface-server` | - |\n| Cohere | `@chroma-core/cohere` | - |\n| Sentence Transformer | `@chroma-core/sentence-transformer` | - |\n| BM25 (稀疏) | `@chroma-core/chroma-bm25` | - |\n\nSources: [clients/new-js/packages/ai-embeddings/all/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/all/package.json)\n\n### 嵌入函数配置示例\n\n```typescript\nimport { ChromaClient } from 'chromadb';\nimport { JinaEmbeddingFunction } from '@chroma-core/jina';\n\n// 初始化Jina嵌入函数\nconst embedder = new JinaEmbeddingFunction({\n apiKey: process.env.JINA_API_KEY,\n modelName: 'jina-embeddings-v2-base-en',\n dimensions: 768,\n normalized: true,\n});\n\n// 创建客户端并指定嵌入函数\nconst client = new ChromaClient({ path: 'http://localhost:8000' });\nconst collection = await client.createCollection({\n name: 'my-collection',\n embeddingFunction: embedder,\n});\n```\n\n### 通用工具包\n\n`@chroma-core/ai-embeddings-common` 包提供了所有嵌入提供者共享的通用工具：\n\n- API请求封装\n- 响应格式标准化\n- 配置验证\n- AJV JSON Schema验证\n\nSources: [clients/new-js/packages/ai-embeddings/common/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/common/package.json)\n\n## API客户端生成\n\n新版客户端使用OpenAPI规范生成类型安全的API客户端：\n\n```mermaid\ngraph LR\n A[OpenAPI Spec] --> B[openapi-generator-plus]\n B --> C[client.gen.ts]\n C --> D[类型定义]\n C --> E[API方法]\n```\n\n生成的API文件位于 `clients/new-js/packages/chromadb/src/api/client.gen.ts`，包含：\n\n- 完整的TypeScript类型定义\n- 请求/响应模型\n- HTTP客户端封装\n\nSources: [clients/new-js/packages/chromadb/src/api/client.gen.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/src/api/client.gen.ts)\n\n## 包配置与导出\n\n### 模块导出配置\n\n新版客户端使用现代化的导出配置，支持ESM和CommonJS：\n\n```json\n{\n \"exports\": {\n \".\": {\n \"import\": {\n \"types\": \"./dist/chromadb.d.ts\",\n \"default\": \"./dist/chromadb.mjs\"\n },\n \"require\": {\n \"types\": \"./dist/cjs/chromadb.d.cts\",\n \"default\": \"./dist/cjs/chromadb.cjs\"\n }\n }\n }\n}\n```\n\nSources: [clients/new-js/packages/chromadb/package.json](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chromadb/package.json)\n\n### 兼容性矩阵\n\n| Node.js版本 | 支持情况 |\n|-------------|---------|\n| >= 20 | 完整支持 (new-js) |\n| >= 14.17.0 | 基础支持 (旧版js) |\n| >= 10 | 原生 bindings |\n\n## 开发与构建\n\n### 构建命令\n\n```bash\n# 新版客户端构建\ncd clients/new-js/packages/chromadb\npnpm build\n\n# 旧版客户端构建\ncd clients/js\npnpm build:core\npnpm build:packages\n\n# 安装依赖\npnpm install\n\n# 运行测试\npnpm test\n```\n\n### 发布流程\n\n```bash\n# 发布正式版本\npnpm release\n\n# 发布Alpha版本\npnpm release_alpha\n\n# 发布开发版本\npnpm release_dev\n```\n\nSources: [clients/js/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/package.json)\n\n## 使用示例\n\n### Node.js环境完整示例\n\n```typescript\nimport { ChromaClient } from 'chromadb';\nimport { JinaEmbeddingFunction } from '@chroma-core/jina';\n\n// 1. 初始化嵌入函数\nconst embedder = new JinaEmbeddingFunction({\n apiKey: process.env.JINA_API_KEY,\n});\n\n// 2. 创建客户端\nconst client = new ChromaClient({\n path: 'http://localhost:8000',\n});\n\n// 3. 创建或获取集合\nconst collection = await client.getOrCreateCollection({\n name: 'documents',\n embeddingFunction: embedder,\n});\n\n// 4. 添加文档\nawait collection.add({\n ids: ['doc1', 'doc2', 'doc3'],\n documents: [\n '机器学习是人工智能的一个分支',\n '深度学习使用神经网络模型',\n '自然语言处理研究人机交互'\n ],\n metadatas: [\n { category: 'ai', year: 2024 },\n { category: 'ml', year: 2024 },\n { category: 'nlp', year: 2024 }\n ]\n});\n\n// 5. 查询相似文档\nconst results = await collection.query({\n queryTexts: ['什么是深度学习？'],\n nResults: 2,\n});\n\nconsole.log('相似文档:', results.documents);\nconsole.log('距离:', results.distances);\n```\n\n### 旧版客户端用法\n\n```typescript\nimport { ChromaClient } from 'chromadb';\n\n// 使用默认配置连接\nconst client = new ChromaClient();\nconst collection = await client.createCollection('test');\n\n// 使用自定义服务器地址\nconst remoteClient = new ChromaClient({\n path: 'https://your-chroma-server.com'\n});\n```\n\nSources: [clients/js/packages/chromadb-client/src/index.ts](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb-client/src/index.ts)\n\n## 依赖管理\n\n### 核心依赖\n\n| 依赖包 | 用途 |\n|--------|------|\n| isomorphic-fetch | 跨平台HTTP请求 |\n| ajv | JSON Schema验证 |\n| cliui | 命令行界面 |\n\n### 嵌入函数peerDependencies (旧版客户端)\n\n```json\n{\n \"peerDependencies\": {\n \"@google/generative-ai\": \"^0.1.1\",\n \"@xenova/transformers\": \"^2.17.2\",\n \"chromadb-default-embed\": \"^2.14.0\",\n \"cohere-ai\": \"^7.0.0\"\n }\n}\n```\n\nSources: [clients/js/packages/chromadb/package.json](https://github.com/chroma-core/chroma/blob/main/clients/js/packages/chromadb/package.json)\n\n## 测试策略\n\n### 测试命令\n\n```bash\n# 运行所有测试\npnpm test\n\n# 运行功能测试（排除认证测试）\npnpm test:functional\n\n# 更新快照测试\npnpm test:update\n```\n\n### 测试环境要求\n\n- Node.js >= 14.17.0\n- Chroma服务器运行于 localhost:8000\n- 可选的认证配置用于auth测试\n\n## 技术选型说明\n\n### 为什么使用tsup\n\ntsup是Chroma JS客户端选用的构建工具，原因如下：\n\n- **零配置**: 自动处理TypeScript和Babel\n- **多格式输出**: 同时生成ESM、CJS、类型定义\n- **性能**: 基于esbuild，构建速度极快\n- **Source Maps**: 支持调试\n\n### 为什么分离嵌入包\n\n新版客户端将嵌入函数分离为独立包的好处：\n\n1. **减少主包体积**: 用户只需安装需要的嵌入提供者\n2. **独立版本管理**: 各嵌入提供者可独立更新\n3. **Tree-shaking**: 构建时可移除未使用的嵌入代码\n4. **灵活性**: 支持自定义嵌入函数实现\n\n## 相关资源\n\n- [官方文档](https://docs.trychroma.com/)\n- [GitHub仓库](https://github.com/chroma-core/chroma)\n- [API参考](./api-reference.md)\n- [嵌入函数指南](./embedding-functions.md)\n\n---\n\n\n\n## 嵌入函数集成\n\n### Related Pages\n\nRelated topics: [Python客户端](#page-python-client), [JavaScript/TypeScript客户端](#page-javascript-client)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [clients/new-js/packages/ai-embeddings/common/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/common/README.md)\n- [clients/new-js/packages/ai-embeddings/all/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/all/README.md)\n- [clients/new-js/packages/ai-embeddings/jina/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/jina/README.md)\n- [clients/new-js/packages/ai-embeddings/morph/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/ai-embeddings/morph/README.md)\n- [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md](https://github.com/chroma-core/chroma/blob/main/clients/new-js/packages/chroma-cloud-qwen/README.md)\n- [clients/new-js/src/embedding-function.ts](https://github.com/chroma-core/chroma/blob/main/clients/new-js/src/embedding-function.ts)\n- [chromadb/utils/embedding_functions/schemas/README.md](https://github.com/chroma-core/chroma/blob/main/chromadb/utils/embedding_functions/schemas/README.md)\n- [schemas/embedding_functions/README.md](https://github.com/chroma-core/chroma/blob/main/schemas/embedding_functions/README.md)\n- [rust/types/src/api_types.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/api_types.rs)\n \n\n# 嵌入函数集成\n\n## 概述\n\n嵌入函数集成是 ChromaDB 中用于将文本、文档或其他数据转换为向量表示的核心机制。ChromaDB 支持多种嵌入提供商的集成，包括 OpenAI、Cohere、Jina、HuggingFace 等云服务，以及本地模型如 Ollama 和 HuggingFace Server。\n\nChromaDB 的嵌入函数设计遵循跨语言兼容性原则，确保 Python 客户端和 JavaScript/TypeScript 客户端能够共享相同的配置模式和验证机制。Sources: [clients/new-js/packages/ai-embeddings/common/README.md]()\n\n## 架构设计\n\n### 整体架构\n\nChromaDB 采用模块化设计，将嵌入函数抽象为可插拔的接口。核心组件包括：\n\n```mermaid\ngraph TD\n A[ChromaDB Client] --> B[Embedding Function Abstraction]\n B --> C[Provider-Specific Implementations]\n C --> D[OpenAI]\n C --> E[Cohere]\n C --> F[Jina]\n C --> G[HuggingFace]\n C --> H[Ollama]\n C --> I[Morph]\n C --> J[Google Gemini]\n C --> K[Voyage AI]\n C --> L[Cloudflare Worker AI]\n \n M[Schema Validation] --> B\n M --> N[base_schema.json]\n M --> O[Provider Schemas]\n```\n\n### 嵌入函数配置流程\n\n嵌入函数在客户端层面进行实例化和配置，然后与集合（Collection）绑定使用：\n\n```mermaid\ngraph LR\n A1[用户代码] --> B1[创建嵌入函数实例]\n B1 --> C1[配置参数验证]\n C1 --> D1[Schema 验证]\n D1 --> E1[与 Collection 绑定]\n E1 --> F1[数据添加时自动嵌入]\n F1 --> G1[查询时自动嵌入查询文本]\n```\n\n## 嵌入函数包结构\n\n### JavaScript/TypeScript 包组织\n\nChromaDB 的 JavaScript 客户端将不同嵌入提供商拆分为独立包，便于按需安装：\n\n| 包名 | 用途 | 源码路径 |\n|------|------|----------|\n| `@chroma-core/ai-embeddings-common` | 通用工具函数 | clients/new-js/packages/ai-embeddings/common/ |\n| `@chroma-core/all` | 所有嵌入提供商的聚合包 | clients/new-js/packages/ai-embeddings/all/ |\n| `@chroma-core/jina` | Jina AI 嵌入 | clients/new-js/packages/ai-embeddings/jina/ |\n| `@chroma-core/morph` | Morph 嵌入 | clients/new-js/packages/ai-embeddings/morph/ |\n| `@chroma-core/chroma-cloud-qwen` | Qwen 云端嵌入 | clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/ |\n\nSources: [clients/new-js/packages/ai-embeddings/all/README.md](), [clients/new-js/packages/ai-embeddings/common/README.md]()\n\n### 通用工具函数\n\n`@chroma-core/ai-embeddings-common` 包提供以下核心功能：\n\n```typescript\n// 导入示例\nimport { validateConfigSchema, snakeCase, isBrowser } from '@chroma-core/ai-embeddings-common';\n\n// 驼峰式转蛇式命名（用于 API 兼容性）\nconst snakeCaseConfig = snakeCase({ modelName: 'text-embedding-3-small' });\n// 结果: { model_name: 'text-embedding-3-small' }\n\n// 检测浏览器环境\nif (isBrowser()) {\n // 浏览器特定逻辑\n}\n\n// 验证嵌入函数配置\nvalidateConfigSchema(config, 'openai');\n```\n\n核心功能包括：\n\n- **Schema 验证**：使用 JSON Schema Draft-07 规范验证嵌入函数配置\n- **命名转换**：将 camelCase JavaScript 对象转换为 snake_case 以匹配 API 规范\n- **环境检测**：识别浏览器与 Node.js 运行环境的差异\n\nSources: [clients/new-js/packages/ai-embeddings/common/README.md]()\n\n## Schema 验证系统\n\n### 跨语言兼容性\n\nChromaDB 在 `schemas/embedding_functions/` 目录维护统一的 JSON Schema 定义，确保 Python 和 JavaScript 客户端的配置保持一致：\n\n```mermaid\ngraph TD\n A[Schema Definition] --> B[Python Client]\n A --> C[JavaScript Client]\n B --> D[validate_config function]\n C --> E[validateConfig function]\n```\n\n### Schema 结构\n\n每个嵌入函数 schema 遵循 JSON Schema Draft-07 规范：\n\n| 字段 | 说明 |\n|------|------|\n| `version` | Schema 版本号 |\n| `title` | Schema 标题 |\n| `description` | 功能描述 |\n| `properties` | 可配置属性 |\n| `required` | 必需属性 |\n| `additionalProperties` | 是否允许额外属性（始终为 false） |\n\n### Python 端验证\n\n```python\nfrom chromadb.utils.embedding_functions.schemas import validate_config\n\n# 验证配置\nconfig = {\n \"api_key_env_var\": \"CHROMA_OPENAI_API_KEY\",\n \"model_name\": \"text-embedding-ada-002\"\n}\nvalidate_config(config, \"openai\")\n```\n\nSources: [chromadb/utils/embedding_functions/schemas/README.md](), [schemas/embedding_functions/README.md]()\n\n## API 类型定义\n\n### Include 枚举\n\n在 Rust 实现中，嵌入函数的返回内容通过 `Include` 枚举控制：\n\n```rust\n#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]\n#[cfg_attr(feature = \"utoipa\", derive(utoipa::ToSchema))]\npub enum Include {\n Distance,\n Document,\n Embedding,\n Metadata,\n Uri,\n}\n```\n\n### IncludeList 默认值\n\n| 方法 | 默认包含字段 |\n|------|-------------|\n| `default_query()` | Document, Metadata, Distance |\n| `default_get()` | Document, Metadata |\n| `all()` | Document, Metadata, Distance, Embedding, Uri |\n\nSources: [rust/types/src/api_types.rs]()\n\n## 嵌入函数实现示例\n\n### Jina 嵌入函数\n\nJina AI 嵌入函数是 ChromaDB 支持的重要嵌入提供商之一：\n\n```typescript\nimport { ChromaClient } from 'chromadb';\nimport { JinaEmbeddingFunction } from '@chroma-core/jina';\n\n// 初始化嵌入函数\nconst embedder = new JinaEmbeddingFunction({\n apiKey: 'your-api-key', // 或设置 JINA_API_KEY 环境变量\n modelName: 'jina-embeddings-v2-base-en',\n task: 'retrieval.passage',\n dimensions: 768,\n lateChunking: false,\n truncate: true,\n normalized: true,\n embeddingType: 'float'\n});\n\n// 创建客户端和集合\nconst client = new ChromaClient({ path: 'http://localhost:8000' });\nconst collection = await client.createCollection({\n name: 'my-collection',\n embeddingFunction: embedder,\n});\n\n// 添加文档（自动嵌入）\nawait collection.add({\n ids: [\"1\", \"2\", \"3\"],\n documents: [\"Document 1\", \"Document 2\", \"Document 3\"],\n});\n\n// 查询（自动嵌入查询文本）\nconst results = await collection.query({\n queryTexts: [\"Sample query\"],\n nResults: 2,\n});\n```\n\n**配置选项**：\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `apiKey` | string | JINA_API_KEY env | API 密钥 |\n| `modelName` | string | jina-embeddings-v2-base-en | 模型名称 |\n| `task` | string | retrieval.passage | 任务类型 |\n| `dimensions` | number | 768 | 向量维度 |\n| `lateChunking` | boolean | false | 延迟分块 |\n| `truncate` | boolean | true | 截断超长文本 |\n| `normalized` | boolean | true | L2 归一化 |\n| `embeddingType` | string | float | 嵌入类型 |\n\nSources: [clients/new-js/packages/ai-embeddings/jina/README.md]()\n\n### Morph 嵌入函数\n\n```typescript\nimport { MorphEmbeddingFunction } from '@chroma-core/morph';\n\nconst morphEmbedding = new MorphEmbeddingFunction({\n api_key: 'your-morph-api-key',\n model_name: 'morph-embedding-v2', // 默认值\n api_base: 'https://api.morphllm.com/v1', // 默认值\n encoding_format: 'float' // 默认值\n});\n```\n\n**配置参数**：\n\n| 参数 | 必需 | 默认值 | 说明 |\n|------|------|--------|------|\n| `api_key` | 否 | 环境变量 | API 密钥 |\n| `model_name` | 否 | morph-embedding-v2 | 模型名称 |\n| `api_base` | 否 | https://api.morphllm.com/v1 | API 基础 URL |\n| `encoding_format` | 否 | float | 编码格式 (float 或 base64) |\n\nSources: [clients/new-js/packages/ai-embeddings/morph/README.md]()\n\n### Qwen 云端嵌入函数\n\n```typescript\nimport { ChromaClient } from 'chromadb';\nimport { ChromaCloudQwenEmbeddingFunction } from '@chroma-core/chroma-cloud-qwen';\n\n// 初始化\nconst embedder = new ChromaCloudQwenEmbeddingFunction({\n apiKey: 'your-api-key',\n model: 'Qwen/Qwen3-Embedding-0.6B',\n});\n\n// 创建集合\nconst collection = await client.createCollection({\n name: 'my-collection',\n embeddingFunction: embedder,\n});\n\n// 添加和查询\nawait collection.add({\n ids: [\"doc1\", \"doc2\", \"doc3\"],\n documents: [\"Document 1\", \"Document 2\", \"Document 3\"],\n});\n\nconst results = await collection.query({\n queryTexts: [\"Sample query\"],\n nResults: 2,\n});\n```\n\n**配置选项**：\n\n| 选项 | 说明 |\n|------|------|\n| `model` | 用于嵌入的模型 |\n| `task` | 生成嵌入的任务 |\n| `instruction_dict` | 任务和目标的自定义指令映射 |\n| `apiKeyEnvVar` | API 密钥环境变量名（默认 CHROMA_API_KEY） |\n\nSources: [clients/new-js/packages/ai-embeddings/chroma-cloud-qwen/README.md]()\n\n## 聚合包使用\n\n`@chroma-core/all` 包导出所有嵌入函数，提供一站式导入：\n\n```typescript\nimport {\n OpenAIEmbeddingFunction,\n CohereEmbeddingFunction,\n JinaEmbeddingFunction,\n GoogleGeminiEmbeddingFunction,\n // ... 以及其他所有提供商\n} from '@chroma-core/all';\n\n// 使用任意嵌入函数\nconst openAIEF = new OpenAIEmbeddingFunction({\n apiKey: 'your-api-key',\n modelName: 'text-embedding-3-small'\n});\n```\n\n**包含的提供商**：\n\n- OpenAI\n- Cohere\n- Jina\n- Google Gemini\n- HuggingFace Server\n- Ollama\n- Together AI\n- Voyage AI\n- Cloudflare Worker AI\n- Default Embedding\n\nSources: [clients/new-js/packages/ai-embeddings/all/README.md]()\n\n## 动态加载机制\n\nChromaDB JavaScript 客户端支持嵌入函数的动态加载，通过配置映射实现按需加载：\n\n```typescript\nexport const getEmbeddingFunction = async (\n client: ChromaClient,\n efConfig?: EmbeddingFunctionConfiguration,\n) => {\n // 检查配置类型\n if (efConfig?.type !== \"known\") {\n return undefined;\n }\n\n // 过滤不支持的函数\n if (unsupportedEmbeddingFunctions.has(efConfig.name)) {\n return undefined;\n }\n\n // 获取包名\n const packageName = pythonEmbeddingFunctions[efConfig.name] || efConfig.name;\n\n // 动态导入\n let embeddingFunction = knownEmbeddingFunctions.get(packageName);\n if (!embeddingFunction) {\n try {\n const fullPackageName = `@chroma-core/${packageName}`;\n await import(fullPackageName);\n embeddingFunction = knownEmbeddingFunctions.get(packageName);\n } catch (error) {\n // 动态加载失败\n }\n }\n\n // 使用 buildFromConfig 工厂方法\n if (embeddingFunction.buildFromConfig) {\n return embeddingFunction.buildFromConfig(constructorConfig, client);\n }\n return undefined;\n};\n```\n\n动态加载的优势：\n\n1. **按需加载**：减少初始包体积\n2. **插件化**：支持第三方嵌入函数扩展\n3. **向后兼容**：支持 Python 端的嵌入函数名称映射\n\nSources: [clients/new-js/src/embedding-function.ts]()\n\n## 使用最佳实践\n\n### 安装策略\n\n```bash\n# 仅安装需要的嵌入函数\nnpm install @chroma-core/jina\n\n# 或安装所有嵌入函数\nnpm install @chroma-core/all\n```\n\n### 环境变量配置\n\n大多数嵌入函数支持通过环境变量设置 API 密钥：\n\n```bash\nexport OPENAI_API_KEY=your-openai-key\nexport JINA_API_KEY=your-jina-key\nexport CHROMA_API_KEY=your-chroma-key\nexport MORPH_API_KEY=your-morph-key\nexport XAI_API_KEY=your-xai-key\n```\n\n### 代码组织\n\n```mermaid\ngraph TD\n A[embedding-functions.ts] --> B[统一导出配置]\n B --> C[createCollection 时引用]\n C --> D[数据操作时自动调用]\n \n A1[embedder.ts] --> B\n A2[openai.ts] --> B\n A3[jina.ts] --> B\n```\n\n建议将嵌入函数配置集中管理，便于维护和更换提供商。\n\n## 总结\n\nChromaDB 的嵌入函数集成系统提供了灵活、高效的向量嵌入能力，支持多种云服务和本地模型。通过统一的 Schema 验证机制和动态加载架构，开发者可以轻松切换不同的嵌入提供商，同时保持跨语言的一致性。该系统设计充分考虑了可扩展性，为未来支持更多嵌入模型奠定了基础。\n\n---\n\n\n\n## 存储系统\n\n### Related Pages\n\nRelated topics: [系统架构](#page-architecture), [向量索引系统](#page-vector-index)\n\n\nRelevant source files
\n\nThe following files were used as context for generating this wiki page:\n\n- [rust/blockstore/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/lib.rs)\n- [rust/blockstore/src/arrow/blockfile.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/blockfile.rs)\n- [rust/blockstore/src/arrow/block/types.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n- [rust/blockstore/src/arrow/root.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n- [rust/blockstore/src/arrow/provider.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n- [rust/blockstore/src/provider.rs](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n- [rust/types/src/sparse_posting_block.rs](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n- [rust/wal3/src/lib.rs](https://github.com/chroma-core/chroma/blob/main/rust/wal3/src/lib.rs)\n \n\n# 存储系统\n\n## 概述\n\nChroma 的存储系统是整个数据库基础设施的核心组件，负责管理向量数据和元数据的持久化存储。该系统采用分层架构设计，主要包括以下核心模块：\n\n- **Blockstore**：块存储抽象层，支持多种后端实现\n- **Arrow Blockfile**：基于 Apache Arrow IPC 格式的列式存储实现\n- **Sparse Posting Block**：稀疏倒排索引块存储\n- **WAL3**：三次写入日志（Write-Ahead Log）机制\n\n存储系统的设计目标是通过统一的 API 抽象，支持内存映射、持久化存储以及远程存储后端，同时保证数据一致性和高性能访问。\n\nSources: [rust/blockstore/src/lib.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/lib.rs)\n\n## 架构分层\n\nChroma 存储系统采用四层架构设计，每一层都有明确的职责边界：\n\n```mermaid\ngraph TD\n A[应用层] --> B[API 层]\n B --> C[Provider 层]\n C --> D[Blockfile 层]\n D --> E[Storage 层]\n \n B1[BlockfileProvider] --> C1[Arrow Blockfile Provider]\n B1 --> B2[HashMap Blockfile Provider]\n \n C1 --> D1[ArrowBlockfileWriter]\n C1 --> D2[ArrowBlockfileReader]\n \n E1[Storage] --> E2[本地文件系统]\n E1 --> E3[远程存储]\n```\n\n### 各层职责\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| API 层 | BlockfileProvider | 统一的读写接口抽象 |\n| Provider 层 | Arrow/HashMap Provider | 特定存储格式的提供者 |\n| Blockfile 层 | ArrowBlockfile | 具体的数据块读写实现 |\n| Storage 层 | Storage | 底层持久化机制 |\n\nSources: [rust/blockstore/src/provider.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n\n## Blockstore 核心抽象\n\n### BlockfileProvider 接口\n\n`BlockfileProvider` 是存储系统的核心抽象接口，提供统一的读写操作入口：\n\n```rust\npub trait ReadKey<'a>:\n Key\n + Into\n + TryFrom<&'a KeyWrapper, Error = InvalidKeyConversion>\n + ArrowReadableKey<'a>\n + Sync\n + 'a\n{\n}\n\npub trait ReadValue<'a>: Value + Readable<'a> + ArrowReadableValue<'a> + Sync + 'a {}\n```\n\n该接口支持两种实现：\n1. **ArrowBlockfileProvider**：基于 Arrow IPC 格式的持久化存储\n2. **HashMapBlockfileProvider**：纯内存存储实现\n\nSources: [rust/blockstore/src/provider.rs:60-90](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n\n### 核心 API 方法\n\n| 方法 | 参数 | 返回值 | 描述 |\n|------|------|--------|------|\n| `read` | `options: BlockfileReaderOptions` | `BlockfileReader` | 读取数据块 |\n| `write` | `options: BlockfileWriterOptions` | `BlockfileWriter` | 写入数据块 |\n| `clear` | - | `Result<(), Box>` | 清空缓存 |\n| `prefetch` | `id`, `prefix_path` | `Result` | 预取数据到缓存 |\n| `storage` | - | `Option>` | 获取底层存储 |\n\nSources: [rust/blockstore/src/provider.rs:120-180](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n\n## Arrow Blockfile 实现\n\n### Arrow Blockfile 概述\n\nArrow Blockfile 是 Chroma 的主要存储实现，基于 Apache Arrow 的 IPC（Inter-Process Communication）格式。这种设计带来以下优势：\n\n- **列式存储**：相同类型的数据连续存储，提升压缩率和扫描效率\n- **零拷贝读取**：通过内存映射实现高效的数据访问\n- **类型安全**：Arrow 格式内置 schema 验证\n\n```mermaid\ngraph LR\n A[写入请求] --> B[BlockDelta]\n B --> C[SparseIndex]\n C --> D[Root]\n D --> E[Block Manager]\n E --> F[持久化存储]\n \n G[读取请求] --> H[Arrow Blockfile Reader]\n H --> I[Footer Parsing]\n I --> J[Record Batch]\n```\n\nSources: [rust/blockstore/src/arrow/blockfile.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/blockfile.rs)\n\n### Block 结构\n\nArrow Blockfile 中的数据块（Block）是存储的最小单元：\n\n```rust\n#[derive(Error, Debug)]\npub enum ArrowLayoutVerificationError {\n #[error(\"Buffer length is not 64 byte aligned\")]\n BufferLengthNotAligned,\n #[error(transparent)]\n IOError(#[from] std::io::Error),\n #[error(transparent)]\n ArrowError(#[from] arrow::error::ArrowError),\n #[error(transparent)]\n InvalidFlatbuffer(#[from] flatbuffers::InvalidFlatbuffer),\n #[error(\"No record batches in footer\")]\n NoRecordBatches,\n #[error(\"More than one record batch in IPC file\")]\n MultipleRecordBatches,\n #[error(\"Invalid message type\")]\n InvalidMessageType,\n #[error(\"Error decoding record batch message as record batch\")]\n RecordBatchDecodeError,\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:1-60](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n### Root 结构与版本管理\n\nRoot 是 Arrow Blockfile 的元数据头部，包含版本信息和块ID列表：\n\n```rust\nimpl RootReader {\n pub(super) fn get_all_block_ids_from_bytes(\n bytes: &[u8],\n id: Uuid,\n ) -> Result, FromBytesError> {\n let mut cursor = std::io::Cursor::new(bytes);\n let arrow_reader = arrow::ipc::reader::FileReader::try_new(&mut cursor, None);\n\n let record_batch = match arrow_reader {\n Ok(mut reader) => match reader.next() {\n Some(Ok(batch)) => batch,\n Some(Err(e)) => return Err(FromBytesError::ArrowError(e)),\n None => {\n return Err(FromBytesError::NoDataError);\n }\n },\n Err(e) => return Err(FromBytesError::ArrowError(e)),\n };\n\n let (version, read_id) = Self::version_and_id_from_record_batch(&record_batch, id)?;\n if read_id != id {\n return Err(FromBytesError::IdMismatch);\n }\n\n Self::block_ids_from_record_batch(&record_batch, version)\n }\n}\n```\n\n版本管理确保数据格式的向前兼容性和向后兼容性。\n\nSources: [rust/blockstore/src/arrow/root.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n### BlockfileWriter 实现\n\n`ArrowUnorderedBlockfileWriter` 是无序写入的实现，适用于高并发场景：\n\n```rust\nimpl ArrowUnorderedBlockfileWriter {\n pub(super) fn new(\n id: Uuid,\n prefix_path: &str,\n block_manager: BlockManager,\n root_manager: RootManager,\n max_block_size_bytes: usize,\n cmek: Option,\n ) -> Self {\n let initial_block = block_manager.create::();\n let sparse_index = SparseIndexWriter::new(initial_block.id);\n // ...\n }\n}\n```\n\nSources: [rust/blockstore/src/arrow/blockfile.rs:100-150](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/blockfile.rs)\n\n## Provider 层实现\n\n### Arrow Blockfile Provider\n\n`ArrowBlockfileProvider` 是生产环境的主要存储提供者：\n\n```rust\n// Fork 操作支持数据分叉\nmatch options.mutation_ordering {\n BlockfileWriterMutationOrdering::Ordered => {\n let file = ArrowOrderedBlockfileWriter::from_root(\n new_id,\n self.block_manager.clone(),\n self.root_manager.clone(),\n new_root,\n options.cmek,\n );\n Ok(BlockfileWriter::ArrowOrderedBlockfileWriter(file))\n }\n BlockfileWriterMutationOrdering::Unordered => {\n let file = ArrowUnorderedBlockfileWriter::from_root(\n new_id,\n self.block_manager.clone(),\n self.root_manager.clone(),\n new_root,\n options.cmek,\n );\n Ok(BlockfileWriter::ArrowUnorderedBlockfileWriter(file))\n }\n}\n```\n\nSources: [rust/blockstore/src/arrow/provider.rs:1-100](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n### 写入选项配置\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `prefix_path` | String | - | 数据路径前缀 |\n| `max_block_size_bytes` | usize | 引擎默认值 | 单个块最大字节数 |\n| `mutation_ordering` | BlockfileWriterMutationOrdering | Ordered | 写入顺序策略 |\n| `fork_from` | Option | None | 从现有块分叉 |\n| `cmek` | Option | None | 客户管理的加密密钥 |\n\nSources: [rust/blockstore/src/arrow/provider.rs:80-120](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n## Sparse Posting Block\n\n稀疏倒排索引块是 Chroma 全文搜索功能的核心数据结构：\n\n```rust\n/// DirectoryBlock 存储每个 posting block 的元数据\n/// body = [ max_offset: u32 LE, max_weight: f32 LE ] × num_entries\npub struct DirectoryBlock(SparsePostingBlock);\n\nimpl DirectoryBlock {\n pub fn new(max_offsets: &[u32], max_weights: &[f32]) -> Result {\n if max_offsets.len() != max_weights.len() {\n return Err(SparsePostingBlockError::MismatchedLengths {\n offsets: max_offsets.len(),\n weights: max_weights.len(),\n });\n }\n // ...\n }\n}\n```\n\n该结构支持高效的词项剪枝，通过 `max_weight` 实现维度级别的权重过滤。\n\nSources: [rust/types/src/sparse_posting_block.rs:1-80](https://github.com/chroma-core/chroma/blob/main/rust/types/src/sparse_posting_block.rs)\n\n## WAL3 日志系统\n\n### WAL3 概述\n\nWAL3（Write-Ahead Log version 3）是 Chroma 的预写日志系统，确保数据在系统崩溃后能够恢复：\n\n```mermaid\ngraph LR\n A[事务开始] --> B[写入 WAL]\n B --> C[写入主存储]\n C --> D[标记事务完成]\n D --> E[定期 Checkpoint]\n E --> F[清理已持久化日志]\n```\n\nWAL3 的核心设计目标：\n1. **原子性**：事务要么全部成功，要么全部回滚\n2. **持久性**：已提交的事务不会丢失\n3. **恢复能力**：崩溃后能够恢复到一致状态\n\nSources: [rust/wal3/src/lib.rs:1-50](https://github.com/chroma-core/chroma/blob/main/rust/wal3/src/lib.rs)\n\n### WAL3 数据格式\n\nWAL3 使用紧凑的二进制格式存储事务日志：\n\n| 字段 | 长度 | 说明 |\n|------|------|------|\n| Magic Number | 4 bytes | 标识 WAL3 格式 |\n| Version | 4 bytes | 格式版本号 |\n| Transaction ID | 8 bytes | 递增的事务标识 |\n| Payload Length | 4 bytes | 数据载荷长度 |\n| Payload | Variable | 实际数据 |\n\nSources: [rust/wal3/src/lib.rs:50-100](https://github.com/chroma-core/chroma/blob/main/rust/wal3/src/lib.rs)\n\n## 错误处理机制\n\n### 错误码映射\n\nChroma 存储系统使用统一的错误码体系：\n\n| 错误类型 | 错误码 | 说明 |\n|----------|--------|------|\n| `BlockLoadError::IOError` | Internal | I/O 操作失败 |\n| `BlockLoadError::ArrowError` | Internal | Arrow 解析错误 |\n| `BlockLoadError::CacheError` | Internal | 缓存访问错误 |\n| `FromBytesError::InvalidArgument` | InvalidArgument | 参数验证失败 |\n| `FromBytesError::IdMismatch` | InvalidArgument | ID 不匹配 |\n| `ArrowLayoutVerificationError` | Internal | 布局验证失败 |\n\nSources: [rust/blockstore/src/arrow/block/types.rs:10-40](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n### Arrow Layout 验证\n\nArrow Blockfile 在读取时执行严格的布局验证：\n\n1. **缓冲区对齐检查**：数据缓冲区必须 64 字节对齐\n2. **Magic 标识检查**：验证 Arrow IPC 文件头\n3. **Record Batch 数量检查**：确保只有一个 record batch\n4. **消息类型验证**：验证消息类型正确\n\n```rust\n#[derive(Error, Debug)]\npub enum ArrowLayoutVerificationError {\n #[error(\"Buffer length is not 64 byte aligned\")]\n BufferLengthNotAligned,\n #[error(\"No record batches in footer\")]\n NoRecordBatches,\n #[error(\"More than one record batch in IPC file\")]\n MultipleRecordBatches,\n // ...\n}\n```\n\nSources: [rust/blockstore/src/arrow/block/types.rs:20-45](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/block/types.rs)\n\n## 数据流与操作流程\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Provider as BlockfileProvider\n participant Writer as ArrowBlockfileWriter\n participant BlockMgr as BlockManager\n participant Storage as Storage\n\n Client->>Provider: write(options)\n Provider->>Writer: create Writer\n Writer->>BlockMgr: create BlockDelta\n loop 数据写入\n Client->>Writer: set(key, value)\n Writer->>BlockMgr: flush if full\n end\n Writer->>Storage: persist blocks\n Storage-->>Writer: confirm\n Writer-->>Provider: Writer ready\n Provider-->>Client: return Writer\n```\n\nSources: [rust/blockstore/src/arrow/blockfile.rs:80-120](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/blockfile.rs)\n\n### 读取流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Provider as BlockfileProvider\n participant Reader as ArrowBlockfileReader\n participant Storage as Storage\n\n Client->>Provider: read(options)\n Provider->>Reader: create Reader\n Reader->>Storage: load Footer\n Storage-->>Reader: Footer bytes\n Reader->>Reader: parse Record Batch\n Reader-->>Provider: Reader ready\n Provider-->>Client: return Reader\n Client->>Reader: get(key)\n Reader-->>Client: value\n```\n\nSources: [rust/blockstore/src/arrow/root.rs:30-80](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/root.rs)\n\n## 性能优化\n\n### 块大小配置\n\n| 参数 | 默认值 | 说明 | 调优建议 |\n|------|--------|------|----------|\n| `max_block_size_bytes` | 系统默认值 | 单块最大容量 | 大值减少块数量，小值提高随机访问 |\n| `pl_block_size` | 特定值 | Posting List 块大小 | 影响倒排索引性能 |\n| `hnsw_ef_search` | 可配置 | HNSW 搜索参数 | 影响召回率和延迟 |\n\nSources: [rust/index/src/spann/types.rs:50-80](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n### 预取机制\n\nBlockfileProvider 支持数据预取以提高读取性能：\n\n```rust\npub async fn prefetch(\n &self,\n id: &uuid::Uuid,\n prefix_path: &str,\n) -> Result> {\n match self {\n BlockfileProvider::HashMapBlockfileProvider(_) => unimplemented!(),\n BlockfileProvider::ArrowBlockfileProvider(provider) => provider\n .prefetch(id, prefix_path)\n .await\n .map_err(|e| Box::new(e) as _),\n }\n}\n```\n\nSources: [rust/blockstore/src/provider.rs:160-180](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/provider.rs)\n\n## 安全特性\n\n### CMEK 支持\n\nChroma 存储系统支持客户管理的加密密钥（Customer-Managed Encryption Keys）：\n\n```rust\nbf_options = bf_options.with_cmek(cmek);\n```\n\n每个块文件都可以使用独立的加密配置，确保敏感数据的隔离保护。\n\nSources: [rust/blockstore/src/arrow/provider.rs:50-70](https://github.com/chroma-core/chroma/blob/main/rust/blockstore/src/arrow/provider.rs)\n\n## 配置参考\n\n### BlockfileWriterOptions 配置\n\n```rust\nlet mut bf_options = BlockfileWriterOptions::new(prefix_path.to_string())\n .max_block_size_bytes(pl_block_size);\nbf_options = bf_options.unordered_mutations();\nif let Some(cmek) = cmek {\n bf_options = bf_options.with_cmek(cmek);\n}\n```\n\n关键配置项：\n- `prefix_path`：数据存储路径前缀\n- `max_block_size_bytes`：块大小限制\n- `unordered_mutations`：启用无序写入模式\n- `fork`：从现有块分叉创建\n- `cmek`：加密配置\n\nSources: [rust/index/src/spann/types.rs:100-130](https://github.com/chroma-core/chroma/blob/main/rust/index/src/spann/types.rs)\n\n## 总结\n\nChroma 的存储系统是一个精心设计的分层架构，核心特点包括：\n\n1. **统一的抽象层**：通过 `BlockfileProvider` 接口支持多种后端实现\n2. **Arrow 列式存储**：利用 Arrow IPC 格式实现高效的列式数据访问\n3. **稀疏索引支持**：通过 DirectoryBlock 和 PostingBlock 支持全文搜索\n4. **WAL3 日志**：确保事务的原子性和持久性\n5. **安全特性**：支持 CMEK 客户管理加密\n6. **灵活配置**：支持块大小、写入顺序、分叉等高级配置\n\n这套存储系统为 Chroma 的向量数据库功能提供了坚实的数据持久化基础，同时保持了良好的可扩展性和性能。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：chroma-core/chroma\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:546206616 | https://github.com/chroma-core/chroma | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：chroma-core/chroma\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:546206616 | https://github.com/chroma-core/chroma | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:546206616 | https://github.com/chroma-core/chroma | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:546206616 | https://github.com/chroma-core/chroma | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# chroma - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 chroma 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Search infrastructure for AI 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：Chroma项目概述。围绕“Chroma项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-data-flow：数据流与处理流程。围绕“数据流与处理流程”模拟一次用户任务，不展示安装或运行结果。\n5. page-vector-index：向量索引系统。围绕“向量索引系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“Chroma项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-data-flow\n输入：用户提供的“数据流与处理流程”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-vector-index\n输入：用户提供的“向量索引系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“Chroma项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-data-flow：Step 4 必须围绕“数据流与处理流程”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-vector-index：Step 5 必须围绕“向量索引系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/chroma-core/chroma\n- https://github.com/chroma-core/chroma#readme\n- README.md\n- chromadb/__init__.py\n- Cargo.toml\n- clients/python/pyproject.toml\n- clients/js/package.json\n- Dockerfile\n- docker-compose.yml\n- rust/frontend/src/lib.rs\n- rust/worker/src/lib.rs\n- go/pkg/sysdb/coordinator/coordinator.go\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 chroma 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：chroma-core/chroma\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install chromadb\n```\n\n来源：https://github.com/chroma-core/chroma#readme\n\n## 来源\n\n- repo: https://github.com/chroma-core/chroma\n- docs: https://github.com/chroma-core/chroma#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_ce6db9c989fb420eb0e8d2f3c80e9153"
}