# 创建 assistant 消息 (/zh/api/assistant/create-assistant-message-v2) Related: [搜索文档](/zh/api/assistant/search.md), [获取页面内容](/zh/api/assistant/get-page-content.md), [检测 AI 风格的文本](/zh/api/admin/deslop.md) assistant 消息 v2 端点兼容 **AI SDK v5+**。如果你正在使用 AI SDK v4，请改用 [assistant 消息 v1 端点](/zh/api/assistant/create-assistant-message)。
## 与 `useChat` 集成 [#与-usechat-集成]
Vercel 的 AI SDK 提供的 `useChat` hook 是在你的应用程序中集成 assistant API 的推荐方式。 ```bash npm i ai@^6 @ai-sdk/react ``` ```tsx import { useState } from "react"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport } from "ai"; function MyComponent({ domain }) { const [input, setInput] = useState(""); const { messages, sendMessage } = useChat({ transport: new DefaultChatTransport({ api: `https://api.mintlify.com/discovery/v2/assistant/${domain}/message`, headers: { Authorization: `Bearer ${process.env.PUBLIC_MINTLIFY_ASSISTANT_KEY}`, }, body: { fp: "anonymous", retrievalPageSize: 5, context: [ { type: "code", value: 'const example = "code snippet";', elementId: "code-block-1", }, ], }, }), }); return (
{messages.map((message) => (
{message.role === "user" ? "User: " : "Assistant: "} {message.parts .filter((part) => part.type === "text") .map((part) => part.text) .join("")}
))}
{ e.preventDefault(); if (input.trim()) { sendMessage({ text: input }); setInput(""); } }} > setInput(e.target.value)} />
); } ``` **必填配置：** * `transport` - 使用 `DefaultChatTransport` 来配置 API 连接。 * `body.fp` - 指纹标识符 (使用 `'anonymous'` 或唯一的用户标识符) 。 * `body.retrievalPageSize` - 要使用的搜索结果数量 (推荐：5) 。 **可选配置：** * `body.context` - 提供给 AI 助手的上下文信息数组。每个 context 对象包含： * `type` - `'code'` 或 `'textSelection'` 之一。 * `value` - 代码片段或选中的文本内容。 * `path` (可选) - 源文件或页面的路径。 * `elementId` (可选) - 包含该 context 的 UI 元素标识符。 * `body.currentPath` - 用户当前正在查看页面的路径。提供该字段时，AI 助手会利用此 context 提供更相关的回答。最大长度：200 个字符。 更多详情参见 AI SDK 文档中的 [useChat](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) 和 [Transport](https://ai-sdk.dev/docs/ai-sdk-ui/transport)。
## 速率限制 [#速率限制]
AI 助手 API 有以下限制： * 每个 Mintlify 组织每小时最多 10,000 个请求 * 每个 IP 地址每天最多 10,000 个请求 `POST /v2/assistant/{domain}/message` 针对指定的 domain，从 AI 助手生成一条回复消息。适用于 AI SDK v5 及更高版本。 使用 assistant API 密钥进行身份验证。 ## OpenAPI ```json { "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "来自你的 `domain.mintlify.site` URL 中的 domain 标识符。你可以在控制台 URL 的末尾找到它。例如，在 `dashboard.mintlify.com/organization/domain` 中，domain 标识符是 `domain`。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fp", "messages" ], "properties": { "fp": { "type": "string", "description": "用于跟踪会话的指纹标识符。对匿名用户使用 `anonymous`，或提供一个唯一的用户标识符。" }, "threadId": { "default": null, "type": "string", "description": "一个可选的标识符，用于在多条消息之间保持会话的连续性。提供该值后，系统会将后续消息关联到同一个会话线程。当 `event.type === 'finish'` 时，响应中会在 `event.threadId` 字段返回该 `threadId`。" }, "messages": { "type": "array", "default": [ { "id": "foobar", "role": "user", "parts": [ { "type": "text", "text": "How do I get started" } ] } ], "items": { "type": "object", "properties": { "id": { "type": "string", "description": "消息的唯一标识符。" }, "role": { "type": "string", "enum": [ "system", "assistant", "user" ], "description": "消息发送者的角色。" }, "createdAt": { "type": "string", "format": "date-time", "description": "消息创建时的时间戳。" }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "description": "文本内容片段。", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "description": "包含可选提供方 metadata 的推理内容片段。", "properties": { "type": { "type": "string", "enum": [ "reasoning" ] }, "text": { "type": "string" }, "providerMetadata": { "type": "object", "description": "可选的、特定于提供方的 metadata。" } }, "required": [ "type", "text" ] }, { "type": "object", "description": "引用来源 URL 的片段。", "properties": { "type": { "type": "string", "enum": [ "source-url" ] }, "sourceId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "providerMetadata": { "type": "object", "description": "可选的、特定于提供方的 metadata。" } }, "required": [ "type", "sourceId", "url" ] }, { "type": "object", "description": "文件附件内容片段。", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "mediaType": { "type": "string" }, "url": { "type": "string" }, "filename": { "type": "string" } }, "required": [ "type", "mediaType", "url" ] }, { "type": "object", "description": "标记一个新步骤开始的片段。", "properties": { "type": { "type": "string", "enum": [ "step-start" ] } }, "required": [ "type" ] } ] }, "description": "消息片段数组。每个片段都有一个类型以及该类型特有的字段。" }, "metadata": { "type": "object", "description": "与消息关联的可选 metadata。" } }, "required": [ "id", "role", "parts" ] }, "description": "会话中的消息数组。使用 @ai-sdk/react 包中的 useChat 钩子提供的 handleSubmit 函数来管理消息和流式响应。" }, "retrievalPageSize": { "type": "number", "default": 5, "description": "用于生成回答时检索的文档搜索结果数量。数值越高，可用的上下文越多，但可能增加响应时间。推荐值：5。" }, "filter": { "type": "object", "default": null, "properties": { "version": { "type": "string", "description": "可选的版本过滤条件。" }, "language": { "type": "string", "description": "可选的语言过滤条件。" }, "groups": { "type": "array", "items": { "type": "string" }, "description": "可选的分组标识符数组，用于筛选结果。" } }, "description": "用于搜索的可选筛选条件。" }, "context": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "code", "textSelection" ], "description": "所提供上下文的类型。" }, "value": { "type": "string", "description": "代码片段或选中文本的内容。" }, "path": { "type": "string", "description": "源文件或页面的可选路径。" }, "elementId": { "type": "string", "description": "包含该上下文的 UI 元素的可选标识符。" } }, "required": [ "type", "value" ] }, "description": "提供给 AI 助手的可选上下文信息数组。" }, "currentPath": { "type": "string", "description": "用户当前正在查看的页面路径。若提供，AI 助手会利用该上下文给出更相关的回答。最大长度：200 个字符。" } } } } } }, "responses": { "200": { "description": "消息已成功生成", "content": { "application/json": { "schema": { "type": "object", "description": "与 AI SDK v5 兼容的流式响应。使用 [@ai-sdk/react 中的 useChat 钩子](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) 来处理响应流。" } } } } } } ```