人工智能大模型AI AgentRAG后端前端【免费下载链接】TaskingAIThe open source platform for AI-native application development.项目地址https://gitcode.com/gh_mirrors/ta/TaskingAI点击查看免费下载本指南基于 TaskingAI 仓库中的官方 Python 代码模板 1_create_record.md系统讲解如何在已创建的 Collection 中创建三种类型的 Record纯文本text、网页 URLweb与上传文件file并深入剖析 TokenTextSplitter 分块、内容加载与落库的底层实现。读完本文你将掌握 TaskingAI Retrieval 体系中向知识库写入数据的完整姿势并能结合 REST API 与测试用例进行验证。前置准备一个已存在的 CollectionRecord 不能脱离 Collection 独立存在。创建 Record 之前你必须先通过 SDK 或 REST API 创建一个 Collection并拿到它的collection_idimport taskingai from taskingai.retrieval import Collection, TokenTextSplitter collection: Collection taskingai.retrieval.create_collection( embedding_model_id$$EMBEDDING_MODEL_ID$$, embedding_size1536, namemy_collection, description用于测试 Record 创建的集合, ) print(fcollection_id: {collection.collection_id})对应 REST 端点为POST /collections后端路由定义见 auto/collection.py。后续所有create_record调用都依赖collection_id参数来定位目标 Collection。方式一通过文本内容创建 Recordtypetext基本代码import taskingai from taskingai.retrieval import Record, TokenTextSplitter # 假设你已经创建了 collection从中获取 collection_id record: Record taskingai.retrieval.create_record( collection_id$$COLLECTION_ID$$, typetext, contentMachine learning is a subfield of artificial intelligence..., text_splitterTokenTextSplitter(chunk_size200, chunk_overlap20), metadata{} )参数说明参数说明约束依据后端 Schemacollection_id目标 Collection 的标识Record 将被存储在该集合下必填type记录类型这里为text枚举text/file/web默认为textcontent记录的文本内容长度 132768 字符见 schemas/retrieval/record.pytext_splitter文本分块器决定如何把长文本切分为 Chunk必填创建后不可修改metadata记录的元数据字典最多 16 个键值对键长 64值长 512见 schemas/retrieval/record.py代码模板文档特别强调两点text_splitter不是 Record 的属性它不会出现在创建后的响应中只参与创建阶段的分块过程。这一点在测试中也得到印证后端测试在断言创建响应时显式跳过text_splitter字段见 tests/services_tests/retrieval/test_record.py。chunk_size与chunk_overlap分别表示每个文本块的最大 token 数与相邻块之间的重叠 token 数chunk_overlap0表示块之间无重叠。TokenTextSplitter 的边界约束TokenTextSplitter底层对应后端TextSplitter模型models/retrieval/text_splitter/text_splitter.py校验规则如下chunk_size取值范围 501000ge50, le1000chunk_overlap取值范围 0200ge0, le200二者必须同时提供token 类型下任一缺失都会抛ValueError强制约束chunk_overlap chunk_size / 2即重叠不能超过块大小的一半否则校验失败。分块实现原理TokenTextSplitter实际执行split_text_by_tokenmodels/retrieval/text_splitter/token_handler.py使用 tiktoken 分词器对整篇文本编码。仓库中默认分词器为tiktoken.encoding_for_model(text-embedding-ada-002)见 models/retrieval/tokenizer/tiktoken.py根据chunk_size与chunk_overlap计算分块数量与平均块大小按 token 边界滑窗切分若传入title还会把标题以{title}\n\n{chunk}的形式拼接到每一个chunk 的开头并将标题 token 数计入各 chunk 的num_tokens。也就是说content不是按字符数而是按 token 数切块切分结果将直接决定后续向量化的粒度。方式二通过网页 URL 创建 Recordtypeweb基本代码import taskingai from taskingai.retrieval import Record, TokenTextSplitter # 假设你已经创建了 collection从中获取 collection_id record: Record taskingai.retrieval.create_record( collection_id$$COLLECTION_ID$$, typeweb, urlhttps://www.tasking.ai, text_splitterTokenTextSplitter(chunk_size200, chunk_overlap20), )web 类型的关键参数是url长度 12048后端 Schema 中明确注释url is required when the record type isweb见 schemas/retrieval/record.py。底层抓取逻辑后端在处理 web 记录时services/retrieval/content_loader/content_loader.py会做以下校验与处理URL 必须是 HTTPSurl.startswith(https://)校验失败会直接拒绝请求通过WebContentLoaderservices/retrieval/content_loader/web.py发起异步抓取默认10 秒超时使用aiohttp请求页面非 200 状态码、非 UTF-8 编码、网络异常或超时都会抛出明确的INVALID_REQUEST错误抓取成功后用BeautifulSoup提取页面纯文本soup.get_text(separator , stripTrue)去掉 HTML 标签后作为待分块内容若抓取内容为空同样拒绝创建。也就是说web 记录在创建时即时抓取页面内容数据库中保存的是页面抓取时间点的文本快照content字段以 JSON 存储{url: ...}真实文本仅用于分块与向量化见 models/retrieval/record.py 的url()辅助方法。方式三通过上传文件创建 Recordtypefile文件方式分两步走先上传文件拿到file_id再基于file_id创建 Record。第一步上传文件from taskingai.file import upload_file new_file taskingai.file.upload_file(fileopen(YOUR_FILE_PATH, rb), purposerecord_file) print(fuploaded file id: {new_file.file_id})上传接口在服务端对应POST /filesroutes/file/file.py重要限制支持格式pdf、docx、md、txt、html、htm见 routes/file/utils.py大小上限单文件15 MB生成的file_id格式为{ext}_{Jde5}{随机20位字符}扩展名会写入文件 ID 前缀供后续内容加载时识别类型文件以purposerecord_file标识用途存储于对象存储S3/MinIO。第二步基于文件创建 Recordrecord: Record taskingai.retrieval.create_record( collection_id$$COLLECTION_ID$$, typefile, titleMachine learning, file_idnew_file.file_id, text_splitter{type: token, chunk_size: 200, chunk_overlap: 20}, ) print(fcreated record: {record.record_id})注意此处text_splitter也可以直接用字典形式传入{type: token, chunk_size: 200, chunk_overlap: 20}与TokenTextSplitter(...)等价后端会将其解析为同一个TextSplitter模型见 operators/retrieval/record.py 的TextSplitter(**create_dict[text_splitter])。文件内容如何被读取后端在load_content_to_split中services/retrieval/content_loader/content_loader.py按file_id的前缀扩展名分发到不同解析器扩展名解析器pdfPdfFileContentLoaderdocxDocxFileContentLoadertxtTxtContentLoaderhtmlHtmlFileContentLoadermdMarkdownFileContentLoader流程为从对象存储下载文件到临时目录 → 解析出纯文本 → 分块与向量化 → 清理临时文件并从对象存储删除原文件。数据库中仅保存{file_id: ..., file_name: ..., file_size: ...}元信息见 content_loader.py真正的文本内容只存在于生成的 Chunk 中。三种类型的统一后端创建流程无论哪种类型create_record在服务端最终都汇聚到RecordModelOperator.createoperators/retrieval/record.py整体流程如下校验参数RecordCreateRequest ↓ 校验 Collection 存在性collection_ops.get ↓ process_content加载原始内容load_db_content load_content_to_split ↓ text_splitter.split_text按 token 切分为 chunk 列表 ↓ 容量检查chunk 数量不得超过 collection.rest_capacity() ↓ 校验 embedding 模型并批量生成向量embed_documents ↓ create_record_and_chunks事务写入 record chunks 更新 collection 统计关键细节容量保护若切分出的 chunk 数超过 Collection 剩余容量会抛出RESOURCE_LIMIT_REACHED提示集合没有足够容量存储新 chunkoperators/retrieval/record.py事务落库create_record_and_chunksdatabase_ops/retrieval/record/create.py在单个数据库事务内完成三件事插入record行状态ready、num_chunks为 chunk 数→ 批量插入所有 chunk 及对应向量 → 原子更新collection的num_records 1与num_chunks N响应结构接口返回{status: success, data: {...}}见 schemas/auto/record_create_response.pydata即 Record 实体包含record_id、collection_id、title、status、num_chunks、type、content、metadata、created_timestamp、updated_timestamp见 models/retrieval/record.pyrecord_id形如qpEa 20 位随机串。进阶separator 分割器与 Record 的更多操作代码模板虽只介绍TokenTextSplitter但后端实际支持两种分块策略TextSplitterType枚举见 text_splitter.pytext_splitter { type: separator, separators: [,, .], # 分隔符列表116 个每项长度 50 chunk_size: 200, chunk_overlap: 100, }separator 模式按显式分隔符切分且校验要求分隔符不能为空字符串、不能互为子串。仓库测试用例中同时覆盖了 token 与 separator 两种分块的创建与回读断言见 tests/services_tests/retrieval/test_record.py可作为你自测的参考蓝本。除创建外REST API 还提供同路径下的查询、分页列表、更新与删除能力routes/auto/record.pyGET /collections/{collection_id}/records/{record_id}获取单个 RecordGET /collections/{collection_id}/records分页列出 Records支持prefix_filter、equal_filter、after/before游标POST /collections/{collection_id}/records/{record_id}更新 Record注意file 类型不可更新后端会直接拒绝见 operators/retrieval/record.pyDELETE /collections/{collection_id}/records/{record_id}删除 Record 及其全部 Chunk。常见错误与排查要点场景提示/行为对策content为空The content is empty检查文本是否被 strip 后为空chunk_overlap chunk_size/2校验ValueError调小chunk_overlap或调大chunk_sizeweb URL 非 HTTPSHTTPS is required for web URL更换为 https:// 链接web 抓取超时10s或非 200INVALID_REQUEST换可稳定访问的页面重试文件格式不支持列出支持格式pdf/docx/md/txt/html/htm转换为支持格式文件超过 15MBFile size is too large.压缩或拆分文件chunk 数超出 Collection 容量RESOURCE_LIMIT_REACHED增大 Collection 容量或删减旧数据小结本指南完整覆盖了 TaskingAI 创建 Record 的三种官方方式text直接写入content文本配合TokenTextSplitterchunk_size501000chunk_overlap0200 且不超过chunk_size/2完成分块web提供 HTTPS 链接服务端即时抓取、解析纯文本后分块file先以purposerecord_file上传≤15MB支持 pdf/docx/md/txt/html/htm再以file_id创建。无论哪种方式text_splitter都只作用于创建阶段、不进入最终响应所有记录最终以Record 多个带向量的 Chunk的形式落库并实时更新 Collection 的统计计数。你可以继续阅读 Retrieval Collection 指南若存在以及 test_record.py 中的完整测试用例进一步掌握记录的分页查询、更新与删除操作。赞分享人工智能大模型AI AgentRAG后端前端【免费下载链接】TaskingAIThe open source platform for AI-native application development.项目地址https://gitcode.com/gh_mirrors/ta/TaskingAI点击查看免费下载相关推荐TaskingAI 检索实战用 Python SDK 创建 Record 的三种方式文本 / Web URL / 文件上传与底层实现解析TaskingAI 检索实战用 Python SDK 创建 Record 的三种方式文本 / Web URL / 文件上传与底层实现解析 导读 Recor人工智能大模型AI AgentRAG后端前端ng-zorro-antd Grid 响应式布局进阶在 nzXs/nzSm/nzMd/nzLg/nzXl/nzXXl 中内嵌 span、offset、push、pull、orderng zorro antd Grid 响应式布局进阶在 nzXs/nzSm/nzMd/nzLg/nzXl/nzXXl 中内嵌 span、offset、push人工智能大模型AI AgentRAG后端前端Sapling 的 Rebase 完全指南用 sl rebase 移动提交的三种方式与底层原理Sapling 的 Rebase 完全指南用 sl rebase 移动提交的三种方式与底层原理 Sapling sl 中所谓的 rebase 本质上是开发工具CLI后端上一篇NVIDIA Profile Inspector解锁显卡隐藏功能的5个实用技巧下一篇如何用开源工具优化显卡性能5个技巧提升游戏体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考