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

导读：本文以 TaskingAI 官方代码模板 Create an Assistant（REST API 版） 为主体，系统讲解如何通过POST /v1/assistants创建一个可投入对话的 Assistant（AI 助手）。文章完整覆盖请求体全部字段（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.py：assistant_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": {} }'

使用前需将模板中的三个占位符替换为你的真实值：

2.2 路由注册与认证鉴权

POST /v1/assistants路由由自动生成脚本注册在 backend/app/routes/auto/assistant.py 中。从源码可以看到该端点具备以下特征：

• 路由路径为/assistants，HTTP 方法为POST，operation_id为create_assistant，响应模型为AssistantCreateResponse；
• 通过Depends(auth_info_required)完成 API Key 鉴权（对应模板中的Authorization: Bearer $$API_KEY$$）；
• 通过Depends(path_params_required)注入路径参数（创建时object_id_required=False，即无需提供assistant_id，ID 由服务端自动生成）；
• 请求体AssistantCreateRequest经 Pydantic 校验后，调用ops.create(create_dict=data.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：固定为"Assistant"；
• assistant_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_length=8, max_length=8, pattern="^[a-zA-Z0-9]+$"）。
• 源码行为：在 backend/app/operators/assistant/assistant.py 中，创建时先通过model_ops.get(model_id=model_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 的MemoryType）：

• 字段取值范围：max_messages为 1–1024；max_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）的行为配置，对应RetrievalConfig（backend/app/models/retrieval/retrieval.py），关键字段：

• 源码级约束：在_validate_retrievals()（backend/app/operators/assistant/assistant.py）中，若retrievals非空且method=function_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_length=16校验）。
• 默认值：空对象{}。

四、创建链路：从请求到落库的源码透视

一次POST /v1/assistants调用在后端经历了如下完整链路：

1. 路由层：auto_add_assistant_routes注册端点（backend/app/routes/auto/assistant.py），完成鉴权与路径参数注入；
2. 请求校验层：AssistantCreateRequest通过 Pydantic 完成字段类型、长度、正则、枚举等校验（backend/app/schemas/auto/assistant_create_request.py）；
3. 业务校验层：assistant_ops.create()（backend/app/operators/assistant/assistant.py）依次执行：
   • 校验model_id对应模型存在且为 chat completion 模型；
   • 校验tools与模型 function call 兼容性；
   • 校验retrievals与retrieval_configs的合法性；
4. 持久化层：调用super().create(...)（PostgresModelOperator，位于 backend/tkhelper/models/operator/postgres_operator.py），将memory、tools、retrievals、retrieval_configs等结构以 JSON 形式写入 PostgreSQL 的assistant表，同时通过 Redis 完成缓存；assistant_id由generate_random_id()自动生成；
5. 响应层：将实体经to_response_dict()序列化后，包装为AssistantCreateResponse（{"status": "success", "data": {...}}）返回。

这条链路也解释了模板中两个易被忽视的设计：assistant_id无需（也不允许）由调用方指定；tools/retrievals即便传[]也会经过校验分支（空列表直接跳过校验）。

五、创建后的下一步：验证与对话

创建成功后，你可以通过GET /v1/assistants/{assistant_id}读取刚创建的助手（模板见 3_get_an_assistant.md）：

curl -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），并支持stream（SSE 流式返回）与debug选项。

提示：除了 REST API 版，TaskingAI 还提供了 Python 同步版（1_python） 与 异步版（2_async_python） 的代码模板，SDK 调用（如taskingai.assistant.create_assistant(...)）与本文的请求参数一一对应，便于在不同编程场景下选择使用。

六、常见问题与最佳实践

1. 模型 ID 报 422 错误：确认model_id是 8 位字母数字且为 chat completion 模型；embedding / rerank 模型不可用于 Assistant。
2. memory 报错：使用message_window时务必同时提供max_messages与max_tokens；max_messages上限 1024、max_tokens上限 8192。
3. tools 与 function call：为助手配置工具或function_call检索方式前，确认绑定的模型支持 function call，否则创建请求会被拒绝。
4. metadata 超限：最多 16 个键值对，key < 64 字符、value < 512 字符。
5. 合理拆分 system prompt：善用system_prompt_template的列表结构与变量机制，将不同场景的提示词拆成独立片段，按变量是否提供来决定是否激活，避免在单个超长字符串里做字符串拼接。
6. 先最小可用再逐步增强：起步时使用"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 Agent
• RAG
• 后端
• 前端