AI 助手消息

为指定的 domain 生成一条由 AI 助手提供的响应消息。

​

与 useChat 集成

Vercel 的 AI SDK 提供的 useChat 钩子是将 AI 助手 API 集成到你的应用中的推荐方式。

Mintlify AI 助手 API 与 AI SDK v4 兼容。如果你使用 AI SDK v5 或更高版本，必须配置自定义 transport。

1. 安装 AI SDK v4

   npm i ai@^4.1.15
   

2. 使用该钩子

   import { useChat } from 'ai/react';
   
   function MyComponent({ domain }) {
     const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
       api: `https://api-dsc.mintlify.com/v1/assistant/${domain}/message`,
       headers: {
         'Authorization': `Bearer ${process.env.MINTLIFY_TOKEN}`,
       },
       body: {
         fp: 'anonymous',
         retrievalPageSize: 5,
       },
       streamProtocol: 'data',
       sendExtraMessageFields: true,
     });
   
     return (
       <div>
         {messages.map((message) => (
           <div key={message.id}>
             {message.role === 'user' ? 'User: ' : 'Assistant: '}
             {message.content}
           </div>
         ))}
         <form onSubmit={handleSubmit}>
           <input value={input} onChange={handleInputChange} />
           <button type="submit">Send</button>
         </form>
       </div>
     );
   }
   

   Mintlify 的必填配置：

   • streamProtocol: 'data' - 启用流式响应所必需。
   • sendExtraMessageFields: true - 发送消息 metadata 所必需。
   • body.fp - 指纹标识符（使用 'anonymous' 或某个用户标识符）。
   • body.retrievalPageSize - 要使用的搜索结果数量（推荐：5）。

在 AI SDK 文档中查看 useChat 以了解更多详情。

​

速率限制

AI 助手 API 的限制如下：

• 每个 key 每月最多使用 10,000 次
• 每个 Mintlify 组织每小时最多 10,000 次请求
• 每个 IP 每日最多 10,000 次请求

Authorizations

Authorization · string · header · required

Authorization 标头需要使用 Bearer 令牌。关于如何获取 API key 的详细信息，请参阅 Assistant API Key 文档。

Path Parameters

domain · string · required

来自你的 domain.mintlify.app URL 的 domain 标识符。你可以在控制台 URL 的末尾找到它。例如，dashboard.mintlify.com/organization/domain 的 domain 标识符是 domain。

Body

application/json

fp · string · required

用于追踪会话会话的指纹标识符。对匿名用户使用“anonymous”，或为用户提供唯一的用户标识符。

messages · object[] · required

会话中的消息数组。在前端开发中，你通常会希望使用 @ai-sdk 包中 useChat hook 提供的 handleSubmit 函数来追加用户消息并处理流式响应，而不是在这个数组中手动定义这些对象，因为它们包含的参数非常多。

显示 子属性

threadId · string

一个可选的标识符，用于在多条消息之间保持会话的连续性。提供该标识符后，系统就可以将后续消息与同一个会话线程关联起来。在响应中，当 event.type === 'finish' 时，会以 event.threadId 的形式返回 threadId。

retrievalPageSize · number · default: 5

用于生成回复时参考的文档搜索结果数量。值越大，可提供的上下文越多，但可能会增加响应时间。推荐值：5。

filter · object

用于搜索的可选筛选条件

显示 子属性

Response

200 - application/json

消息已成功生成

响应对象会以指定的状态码、响应头和内容来流式传输格式化的数据流片段。这与 AI SDK 在文档 ai-sdk.dev/docs/ai-sdk-ui/streaming-data 中所述的预期格式一致。与其编写你自己的解析器，推荐使用 AI SDK 中的 useChat hook（详见文档：链接）。