人工智能大模型AI AgentRAG后端前端【免费下载链接】TaskingAIThe open source platform for AI-native application development.项目地址https://gitcode.com/gh_mirrors/ta/TaskingAI点击查看免费下载导读本文以 TaskingAI 官方代码模板 Create an AssistantREST API 版 为主体系统讲解如何通过POST /v1/assistants创建一个可投入对话的 AssistantAI 助手。文章完整覆盖请求体全部字段model_id、memory、system_prompt_template、tools、retrievals、retrieval_configs、metadata等的语义、取值范围与默认行为并结合 TaskingAI 后端源码剖析创建链路中的校验逻辑、响应结构与底层数据落库方式。读完本文你将掌握在本地启动的 TaskingAI 服务中通过 cURL 一行命令创建 Assistant 的完整技能并能从源码层面理解每个配置项的真实影响为后续的 Chat 对话与消息生成做好准备。一、先认识 TaskingAI 中的 Assistant在 TaskingAI 中Assistant 是一个带有模型、人设与能力的可复用智能体实体。它把三个关键要素绑定在一起语言模型通过model_id指向项目内一个已配置的 chat completion 模型如 OpenAI、Anthropic、通义、智谱等经 TaskingAI 接入的模型人设与上下文通过system_prompt_template定义助手的角色、语气与工作流能力扩展通过memory记忆、tools工具、retrievals检索增强让助手具备长期记忆、调用外部 API 与基于知识库回答问题的能力。从后端模型定义看Assistant 的核心字段与数据模型一一对应见 backend/app/models/assistant/assistant.pyassistant_id、model_id、name、description、system_prompt_template、memory、tools、retrievals、retrieval_configs、metadata以及created_timestamp/updated_timestamp。每个 Assistant 在数据库中由assistant_id作为主键见同一文件的table_name()与id_field_name()并持久化于assistant表。创建 Assistant 是使用 TaskingAI 的第一步只有先创建 Assistant才能进一步创建 Chat、发送 Message 并触发对话生成对应代码模板目录 backend/resources/code_templates/assistant/3_rest_api/2_chat/ 与3_message/中的系列接口。二、创建 Assistant 的 REST API 调用2.1 端点与请求示例创建 Assistant 的端点为POST /v1/assistants。官方代码模板 1_create_an_assistant.md 给出了完整的 cURL 示例curl -X POST $$SERVICE_HOST$$/v1/assistants \ -H Authorization: Bearer $$API_KEY$$ \ -H Content-Type: application/json \ -d { model_id: $$MODEL_ID$$, name: My Assistant, description: A helpful assistant, system_prompt_template: [ You are a professional assistant speaking {{language}}. ], memory: { max_messages: 20, max_tokens: 2000, type: message_window }, tools: [], retrievals: [], retrieval_configs: {}, metadata: {} }使用前需将模板中的三个占位符替换为你的真实值占位符含义$$SERVICE_HOST$$你启动的 TaskingAI 服务地址默认本地部署为http://localhost:8000$$API_KEY$$你的项目 API Key用于Authorization: Bearer认证$$MODEL_ID$$项目内一个已存在的 chat completion 模型 ID2.2 路由注册与认证鉴权POST /v1/assistants路由由自动生成脚本注册在 backend/app/routes/auto/assistant.py 中。从源码可以看到该端点具备以下特征路由路径为/assistantsHTTP 方法为POSToperation_id为create_assistant响应模型为AssistantCreateResponse通过Depends(auth_info_required)完成 API Key 鉴权对应模板中的Authorization: Bearer $$API_KEY$$通过Depends(path_params_required)注入路径参数创建时object_id_requiredFalse即无需提供assistant_idID 由服务端自动生成请求体AssistantCreateRequest经 Pydantic 校验后调用ops.create(create_dictdata.model_dump(), **path_params)完成创建最后包装为AssistantCreateResponse返回。2.3 响应结构创建成功后接口返回AssistantCreateResponse定义见 backend/app/schemas/auto/assistant_create_response.py其结构为{ status: success, data: { } }其中data为完整的新 Assistant 对象。其字段结构与to_response_dict()backend/app/models/assistant/assistant.py一一对应包含object固定为Assistantassistant_id自动生成的助手 ID采用X5lM前缀加随机字符见 backend/app/models/assistant/assistant.py 的generate_random_id()model_id、name、description、system_prompt_template、memory、tools、retrievals、retrieval_configs、metadata与创建请求体一致created_timestamp/updated_timestamp创建与最近更新时间毫秒时间戳。说明模型本身还包含num_chats使用该助手的会话数但通过fields_exclude_in_response()见 backend/app/models/assistant/assistant.py在 API 响应中被排除因此上面的字段列表不包含它。三、请求体参数详解核心配置官方模板列出了create_assistant的完整参数。结合后端请求模型 backend/app/schemas/auto/assistant_create_request.py 与字段定义 backend/tkhelper/schemas/field.py下面逐一深入讲解每个字段3.1model_id必填语义项目内一个 chat completion 模型对话生成模型的 ID。校验规则必须是 8 位字母数字字符串min_length8, max_length8, pattern^[a-zA-Z0-9]$。源码行为在 backend/app/operators/assistant/assistant.py 中创建时先通过model_ops.get(model_idmodel_id)校验模型存在再调用model.is_chat_completion()判断是否为 chat completion 模型若不是则抛出Model {model_id} is not a valid chat completion model.的 422 校验错误。注意embedding 或 rerank 类型的模型不能用作 Assistant 的model_id。3.2name可选默认值空字符串。长度限制0 到 127 字符见name_field()backend/tkhelper/schemas/field.py。用途助手的显示名称便于在控制台与列表中识别。3.3description可选默认值空字符串。长度限制0 到 512 字符见description_field()backend/tkhelper/schemas/field.py。用途对助手用途、能力的一段简要说明。3.4system_prompt_template可选语义一个字符串列表List[str]列表中的每个元素是一段系统提示词片段用于定义助手的对话流程与上下文多个片段在生成时会按顺序拼接。变量占位提示词中的变量用双花括号包裹例如You are a professional assistant speaking {{language}}.变量值在消息生成阶段通过system_prompt_variables传入见 backend/app/schemas/assistant/generate.py 的MessageGenerateRequest。源码级行为在 backend/app/services/assistant/generation/utils.py 的build_system_prompt()中系统会用re.findall(r{{(.*?)}}, prompt)提取模板变量并替换若某个模板片段包含未提供值的变量该片段会被整体跳过最终所有有效片段以\n\n拼接若存在检索文档retrieval_doc还会追加RELATED DOCUMENT段落。因此你可以把提示词拆成多个片段按需动态激活例如按语言、按用户身份条件拼接。3.5memory必填默认{type: zero}语义助手的记忆配置决定对话历史如何被保留与截断。三种记忆类型见 backend/app/models/assistant/memory/assistant_memory.py 的MemoryTypetype说明附加字段zero零记忆不保留任何对话历史无naive朴素记忆完整保留所有历史消息无message_window消息窗口记忆按条数/Token 上限保留最近的对话max_messages必填、max_tokens必填字段取值范围max_messages为 1–1024max_tokens为 1–8192。校验逻辑模型校验器要求message_window类型必须提供max_messages否则抛出the max_messages field is required for the message_window memory type.错误backend/app/models/assistant/memory/assistant_memory.py。模板示例中展示的message_window配置即为最多记住最近 20 条消息、最多 2000 Token。默认行为若请求体中省略memory字段服务端在读取数据库时会回退为{type: zero}见 backend/app/models/assistant/assistant.py。而前端控制台通常默认{type: naive}。建议在 API 调用时显式指定type字段以免得到不符合预期的记忆策略。3.6tools可选语义增强助手能力的工具列表例如插件plugin与动作action。结构每个元素为{ type: plugin | action, id: tool_id }对应 backend/app/models/tool/tool.py 的ToolRef。源码级约束在 backend/app/operators/assistant/assistant.py 的_validate_tools()中若tools非空会调用model.allow_function_call()检查所绑定的模型是否支持 function call不支持则直接报错例如 OpenAI、通义等支持 function call 的模型可用纯 embedding 或部分基础模型不可用随后通过verify_tools(tools)位于 backend/app/services/tool逐个校验工具是否存在且可用。提示模板示例中tools: []表示暂不挂载任何工具这是最简单的起步配置。3.7retrievals与retrieval_configs可选retrievals检索源列表目前仅支持collection知识库集合类型元素结构为{ type: collection, id: collection_id }对应 backend/app/models/retrieval/retrieval.py 的RetrievalRef。retrieval_configs检索增强RAG的行为配置对应RetrievalConfigbackend/app/models/retrieval/retrieval.py关键字段字段默认值取值范围说明top_k31–20检索时返回的相关文本块chunk最大数量max_tokensnull≥ 1检索文本块的 Token 总量上限score_thresholdnull0.0–1.0检索结果的最低相关度阈值低于该分数被过滤methoduser_message服务端默认function_call/user_message/memory检索触发方式模型函数调用触发、用户消息触发或记忆触发function_descriptionnull字符串当methodfunction_call时用于引导模型何时触发检索函数的描述源码级约束在_validate_retrievals()backend/app/operators/assistant/assistant.py中若retrievals非空且methodfunction_call同样要求模型支持 function call随后通过verify_retrievals(retrievals)位于 backend/app/services/retrieval校验集合存在性。关于空对象{}模板示例中retrieval_configs: {}表示不配置检索行为此时retrievals也为空检索功能不生效。若你为助手配置了检索源则应显式提供完整的retrieval_configs。3.8metadata可选语义附加的元数据键值对用于给助手打标签、存备注等。容量限制最多16 个键值对每个 key 长度小于 64 字符、每个 value 长度小于 512 字符见 backend/tkhelper/schemas/field.py 的metadata_field()请求模型中也以max_length16校验。默认值空对象{}。四、创建链路从请求到落库的源码透视一次POST /v1/assistants调用在后端经历了如下完整链路路由层auto_add_assistant_routes注册端点backend/app/routes/auto/assistant.py完成鉴权与路径参数注入请求校验层AssistantCreateRequest通过 Pydantic 完成字段类型、长度、正则、枚举等校验backend/app/schemas/auto/assistant_create_request.py业务校验层assistant_ops.create()backend/app/operators/assistant/assistant.py依次执行校验model_id对应模型存在且为 chat completion 模型校验tools与模型 function call 兼容性校验retrievals与retrieval_configs的合法性持久化层调用super().create(...)PostgresModelOperator位于 backend/tkhelper/models/operator/postgres_operator.py将memory、tools、retrievals、retrieval_configs等结构以 JSON 形式写入 PostgreSQL 的assistant表同时通过 Redis 完成缓存assistant_id由generate_random_id()自动生成响应层将实体经to_response_dict()序列化后包装为AssistantCreateResponse{status: success, data: {...}}返回。这条链路也解释了模板中两个易被忽视的设计assistant_id无需也不允许由调用方指定tools/retrievals即便传[]也会经过校验分支空列表直接跳过校验。五、创建后的下一步验证与对话创建成功后你可以通过GET /v1/assistants/{assistant_id}读取刚创建的助手模板见 3_get_an_assistant.mdcurl -X GET $$SERVICE_HOST$$/v1/assistants/$$ASSISTANT_ID$$ \ -H Authorization: Bearer $$API_KEY$$ \ -H Content-Type: application/json随后进入对话流程先用POST /v1/assistants/{assistant_id}/chats创建 Chat再通过POST /v1/assistants/{assistant_id}/chats/{chat_id}/messages发送用户消息最后调用POST /v1/assistants/{assistant_id}/chats/{chat_id}/messages/generate生成回复对应 backend/resources/code_templates/assistant/3_rest_api/2_chat/ 与 backend/resources/code_templates/assistant/3_rest_api/3_message/ 系列模板。生成时system_prompt_template中的变量通过MessageGenerateRequest.system_prompt_variables传入backend/app/schemas/assistant/generate.py并支持streamSSE 流式返回与debug选项。提示除了 REST API 版TaskingAI 还提供了 Python 同步版1_python 与 异步版2_async_python 的代码模板SDK 调用如taskingai.assistant.create_assistant(...)与本文的请求参数一一对应便于在不同编程场景下选择使用。六、常见问题与最佳实践模型 ID 报 422 错误确认model_id是 8 位字母数字且为 chat completion 模型embedding / rerank 模型不可用于 Assistant。memory 报错使用message_window时务必同时提供max_messages与max_tokensmax_messages上限 1024、max_tokens上限 8192。tools 与 function call为助手配置工具或function_call检索方式前确认绑定的模型支持 function call否则创建请求会被拒绝。metadata 超限最多 16 个键值对key 64 字符、value 512 字符。合理拆分 system prompt善用system_prompt_template的列表结构与变量机制将不同场景的提示词拆成独立片段按变量是否提供来决定是否激活避免在单个超长字符串里做字符串拼接。先最小可用再逐步增强起步时使用tools: []、retrievals: []、retrieval_configs: {}的最小配置创建 Assistant验证对话链路后再逐步接入工具与知识库检索便于定位问题。相关资源本文主体模板backend/resources/code_templates/assistant/3_rest_api/1_assistant/1_create_an_assistant.md路由实现backend/app/routes/auto/assistant.py请求模型backend/app/schemas/auto/assistant_create_request.py实体模型backend/app/models/assistant/assistant.py业务操作backend/app/operators/assistant/assistant.py记忆模型backend/app/models/assistant/memory/assistant_memory.py检索配置backend/app/models/retrieval/retrieval.py提示词构建backend/app/services/assistant/generation/utils.py其余 REST 模板assistant/3_rest_api/2_chat/与assistant/3_rest_api/3_message/目录赞分享人工智能大模型AI AgentRAG后端前端【免费下载链接】TaskingAIThe open source platform for AI-native application development.项目地址https://gitcode.com/gh_mirrors/ta/TaskingAI点击查看免费下载相关推荐TaskingAI 获取单个 Assistant 详解GET /v1/assistants/{assistant_id} 的 REST API 调用与底层实现TaskingAI 获取单个 Assistant 详解GET /v1/assistants/{assistant_id} 的 REST API 调用与底层实现人工智能大模型AI AgentRAG后端前端AiShortChatGPT-Shortcut项目部署实战指南标准部署、离线版、配置自定义与自动同步AiShortChatGPT Shortcut项目部署实战指南标准部署、离线版、配置自定义与自动同步 本文面向想要自托管或二次定制 AiShort 的开发人工智能大模型AI AgentRAG后端前端TextureAsyncDisplayKit自动布局容器实战指南LayoutSpec 组合与 ASLayoutable 属性详解TextureAsyncDisplayKit自动布局容器实战指南LayoutSpec 组合与 ASLayoutable 属性详解 导读 本文以 Textu人工智能大模型AI AgentRAG后端前端上一篇developer-roadmap Angular 路线之 Multiple Locales多语言环境配置、构建与部署实战指南下一篇Go-SQLite3终极安装指南彻底解决CGO编译难题的完整方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考