- 人工智能
- 大模型
- AI Agent
- RAG
- 后端
- 前端
【免费下载链接】TaskingAI
The open source platform for AI-native application development.
导读：本文以 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": {} }'使用前需将模板中的三个占位符替换为你的真实值：
| 占位符 | 含义 |
|---|---|
$$SERVICE_HOST$$ | 你启动的 TaskingAI 服务地址，默认本地部署为http://localhost:8000 |
$$API_KEY$$ | 你的项目 API Key，用于Authorization: Bearer认证 |
$$MODEL_ID$$ | 项目内一个已存在的 chat completion 模型 ID |
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）：
type | 说明 | 附加字段 |
|---|---|---|
zero | 零记忆，不保留任何对话历史 | 无 |
naive | 朴素记忆，完整保留所有历史消息 | 无 |
message_window | 消息窗口记忆，按条数/Token 上限保留最近的对话 | max_messages（必填）、max_tokens（必填） |
- 字段取值范围：
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），关键字段：
| 字段 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|
top_k | 3 | 1–20 | 检索时返回的相关文本块（chunk）最大数量 |
max_tokens | null | ≥ 1 | 检索文本块的 Token 总量上限 |
score_threshold | null | 0.0–1.0 | 检索结果的最低相关度阈值，低于该分数被过滤 |
method | user_message（服务端默认） | function_call/user_message/memory | 检索触发方式：模型函数调用触发、用户消息触发或记忆触发 |
function_description | null | 字符串 | 当method=function_call时，用于引导模型何时触发检索函数的描述 |
- 源码级约束：在
_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调用在后端经历了如下完整链路：
- 路由层：
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.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(...)）与本文的请求参数一一对应，便于在不同编程场景下选择使用。
六、常见问题与最佳实践
- 模型 ID 报 422 错误：确认
model_id是 8 位字母数字且为 chat completion 模型；embedding / rerank 模型不可用于 Assistant。 - memory 报错：使用
message_window时务必同时提供max_messages与max_tokens；max_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 Agent
- RAG
- 后端
- 前端
【免费下载链接】TaskingAI
The open source platform for AI-native application development.
相关推荐
TaskingAI 获取单个 Assistant 详解：GET /v1/assistants/{assistant_id} 的 REST API 调用与底层实现
TaskingAI 获取单个 Assistant 详解：GET /v1/assistants/{assistant_id} 的 REST API 调用与底层实现
人工智能大模型AI AgentRAG后端前端AiShort（ChatGPT-Shortcut）项目部署实战指南：标准部署、离线版、配置自定义与自动同步
AiShort（ChatGPT Shortcut）项目部署实战指南：标准部署、离线版、配置自定义与自动同步 本文面向想要自托管或二次定制 AiShort 的开发
人工智能大模型AI AgentRAG后端前端Texture（AsyncDisplayKit）自动布局容器实战指南：LayoutSpec 组合与 ASLayoutable 属性详解
Texture（AsyncDisplayKit）自动布局容器实战指南：LayoutSpec 组合与 ASLayoutable 属性详解 导读 本文以 Textu
人工智能大模型AI AgentRAG后端前端
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
