• 人工智能
• 大模型
• AI Agent
• RAG
• 后端
• 前端

在 TaskingAI 的检索（Retrieval）体系中，Collection（集合）是承载向量化知识库的最顶层容器：它绑定一个文本嵌入（Text Embedding）模型、规定容量上限，并作为 Record 与 Chunk 的父级资源存在。本篇指南以官方代码模板 1_create_a_collection.md 为核心，完整讲解通过Async Python SDK创建 Collection 的参数含义、同步 SDK 与 REST API 的等价写法，并深入到 TaskingAI 服务端源码，剖析创建 Collection 时实际发生的建表、向量索引构建与参数校验过程，帮助你理解"一个 Collection 在系统里到底代表什么"。

Collection 是什么：检索系统的知识库容器

在 TaskingAI 中，检索模块的层级关系是Collection（集合）→ Record（记录）→ Chunk（文本块）：Collection 是顶层容器，Record 是被切分的原始文档，Chunk 是最终参与向量检索的最小文本单元。

从数据模型 collection.py 可以看到，一个 Collection 实体包含以下核心字段：

创建 Collection 时，你只需要提供embedding_model_id、capacity、name、description（及可选的metadata），其余字段由服务端生成与维护。

使用 Async Python SDK 创建 Collection

官方文档给出的异步写法如下（来自 1_create_a_collection.md）：

import taskingai collection = await taskingai.retrieval.a_create_collection( embedding_model_id="$$MODEL_ID$$", capacity=1000, name="machine learning", description="The evolving history and application of machine learning" )

要点说明：

• $$MODEL_ID$$是代码模板中的占位符，实际使用时需替换为你已创建好的文本嵌入模型（type 为text_embedding）的 8 位模型 ID；
• 函数前缀a_表示 async 版本，必须运行在异步环境中（例如asyncio.run()或 async 函数体内）；
• 调用成功后，返回的collection对象即包含上述全部字段的集合实体，其status为ready。

同步 Python SDK 写法

如果你使用同步风格的 SDK，官方在 1_python/1_collection/1_create_a_collection.md 中提供了等价写法：

import taskingai collection = taskingai.retrieval.create_collection( embedding_model_id="$$MODEL_ID$$", capacity=1000, name="machine learning", description="The evolving history and application of machine learning" )

两种写法参数完全一致，仅同步/异步 API 命名不同。

等价实现：REST API 方式

Collection 的创建同样通过 REST API 暴露，路由定义在 backend/app/routes/auto/collection.py，对应端点POST /v1/collections。官方 REST 模板见 3_rest_api/1_collection/1_create_a_collection.md：

curl -X POST $$SERVICE_HOST$$/v1/collections \ -H "Authorization: Bearer $$API_KEY$$" \ -H "Content-Type: application/json" \ -d '{ "name": "History of Art", "description": "", "capacity": 1000, "embedding_model_id": "$$MODEL_ID$$", "metadata": {} }'

其中$$SERVICE_HOST$$为 TaskingAI 服务地址、$$API_KEY$$为你的 API 密钥占位符。响应体为{"status": "success", "data": {...}}，data中即包含新创建的 Collection 完整信息。

请求参数校验：字段边界与约束

无论走 SDK 还是 REST API，服务端都会统一经过CollectionCreateRequest校验，定义见 collection_create_request.py：

注意capacity虽然 Schema 层面只约束非负，但在操作层（operators/retrieval/collection.py）有硬性限制：allowed_capacity = [1000]，传入其他值（如 900）会返回REQUEST_VALIDATION_ERROR（HTTP 422）。这一点也被测试用例明确覆盖，见 test_collection.py。

创建背后的服务端流程：建表与 HNSW 向量索引

理解"创建 Collection"并不仅仅是往数据库插入一行记录。从数据库操作层 create.py 可以看到，一次创建在同一个 PostgreSQL 事务内完成三步核心动作：

1. 插入 collection 主表记录：将collection_id、name、description、capacity、embedding_model_id、embedding_size、status（置为ready）、metadata写入collection表；
2. 为集合创建专属 chunk 表：表名为c1_{collection_id}（命名规则见 collection.py）。该表含chunk_id、record_id、content、num_tokens、extra、metadata以及关键列embedding vector({embedding_size})，并级联关联record表；
3. 创建 HNSW 向量索引：基于embedding列（vector_cosine_ops）建立 HNSW 索引，索引参数m与ef_construction由容量和向量维度决定。

这里的m与ef_construction由工具函数 utils.py 计算：当capacity <= 1000时取m = 8, ef_construction = 32；而查询阶段的ef_search则按ef_construction * 0.65估算（utils.py）。这意味着capacity不只决定"能存多少 Chunk"，还直接影响了 HNSW 索引的构建与检索参数，是检索性能的重要决定因素之一。

嵌入模型的校验：不是任意模型都能建集合

创建 Collection 前，服务端会校验embedding_model_id是否合法（operators/retrieval/collection.py）：

• 模型必须存在；
• 模型类型必须为text_embedding（对应 model.py 中的is_text_embedding()判断）；
• 模型的properties中必须带有embedding_size字段，用于确定 chunk 表的向量维度。

任一条件不满足，都会返回REQUEST_VALIDATION_ERROR。因此，创建 Collection 之前，请先在 TaskingAI 中配置好一个文本嵌入模型（例如 OpenAI、Cohere、Jina 等支持的嵌入模型），拿到它的模型 ID。

为什么 name 与 description 会影响检索性能

官方模板在代码之后特别强调了一句话，这也是本文需要着重传达的实战要点：

Please properly set collection name and description with meaningful texts. This may affect the performance of your retrieval system.

即：请为集合设置有实际含义的 name 与 description，这可能影响检索系统的性能。原因可以从产品与工程两个层面理解：

• 语义组织层面：有意义的名称与描述帮助你在多个集合并存时（例如"机器学习"与"艺术史"两个知识库）正确选择检索目标，避免把查询发往无关集合而"检索到"噪声内容；
• 工程运维层面：集合名/描述是可读标识，用于排查日志、筛选列表（服务端支持按name前缀过滤，见 test_collection.py）与团队协作，命名混乱的集合在实际检索调优时难以定位。

因此，创建时不要留空name或用无意义的占位文本，应当像示例一样使用"machine learning"+"The evolving history and application of machine learning"这种明确表达主题的写法。

测试验证：官方用例如何覆盖创建行为

仓库测试 test_collection.py 演示了创建集合的完整验收标准，可作为自测参考：

• 创建请求返回200，status == "success"，且data.status == "ready"；
• 返回的data中各字段与请求参数一一相等；
• 请求中可省略name/description/metadata（Schema 允许空值），capacity与embedding_model_id必填；
• 创建后可立即通过GET /collections/{collection_id}查询到该集合；
• 非法容量（如capacity: 900）返回422 REQUEST_VALIDATION_ERROR。

在本地跑服务后，你可以用相同步骤快速验证自己的创建代码是否通过。

小结

创建 Collection 是 TaskingAI 检索链路的第一步，也是决定后续检索质量的基础。通过本篇你可以掌握：

1. 使用taskingai.retrieval.a_create_collection(...)创建集合，以及同步写法与POST /v1/collectionsREST 等价方式；
2. 关键参数embedding_model_id、capacity、name、description、metadata的取值与校验边界（capacity当前固定为 1000，模型必须是text_embedding类型）；
3. 创建背后的源码级事实：集合专属 chunk 表（c1_{id}）、HNSW 余弦向量索引及其m/ef_construction参数推导；
4. 为什么有意义的name与description对检索系统性能至关重要。

创建好 Collection 之后，下一步就是向其写入 Record（调用 1_create_record.md 的a_create_record），文档经切分后生成 Chunk，随后即可通过 Query Chunks 执行向量检索。

• 人工智能
• 大模型
• AI Agent
• RAG
• 后端
• 前端