# web.rest.aiChat 库模块帮助文档 [ ▶ 调用 AI 大模型指南](https://www.aardio.com/zh-cn/docs/library-guide/std/web/rest/aiChat.html) [ ▶ 入门范例](https://www.aardio.com/zh-cn/docs/examples/AI/aiChat.html) ## web.rest 成员列表 # ### web.rest.aiChat # 用于调用 OpenAI Chat Completions、OpenAI Responses、Anthropic、Google 或 Vertex 等 AI 聊天接口。 [范例](https://www.aardio.com/zh-cn/docs/examples/AI/aiChat.html)。如果需要 Web 聊天界面可参考 web.form.chat 库源码。 ### web.rest.aiChat() # [返回对象:webRestAiChatObject](#webRestAiChatObject) ### web.rest.aiChat(config) # ```aardio web.rest.aiChat( proxy = proxy, model = "model-id", temperature = 0.1, maxTokens = 1024, url = "" )/*创建 AI 聊天客户端。参数说明： - url 字段指定 OpenAI,Anthropic,Gemini 等兼容接口网址，如果网址路径为空或`/anthropic`且尾部不是 `/` 则自动追加`/v1`后缀。 - model 字段指定模型名称。 - 可选用 protocol 字段指定 "openai","responses","anthropic","google","vertex" 等接口协议。其中 "responses" 使用 OpenAI Responses HTTP/SSE，固定 store=false 并在本地重放临时工具链。 - 可选用 proxy 字段指定代理服务器，代理格式: https://www.aardio.com/zh-cn/docs/library-guide/std/inet/proxy.html - 可选用 userAgent 字段指定用户代理。 - 关于 temperature 参数请参考: https://www.aardio.com/zh-cn/docs/guide/ide/ai.html#temperature - 可选指定 topP，但一般建议调整 temperature 而不是 topP，topP 不指定保持默认值即可。 - 可选用 maxTokens 限定最大回复长度。 - 可选指定 tools 字段以支持 function call 。 - 可选用 toolChoice 字段指定工具调用规则，默认值为 "auto"。 - 可选用字段 stop 指定停止输出的 token 或 token 数组。 - 可选使用 reasoning.effort / reasoning.maxTokens 字段控制推理强度。 - 部分模型支持 thinking 字段配置思考模式 - 可选用 extraParameters, extraUrlParameters 字段指定附加参数表（table）*/ ``` ## webRestAiChatObject 成员列表 # ### webRestAiChatObject._http # inet.http客户端，用于执行 http 请求 [返回对象:inetHttpObject](https://www.aardio.com/zh-cn/docs/library-reference/inet/http.html#inetHttpObject) ### webRestAiChatObject._protocol # 会自动设置为 "openai","responses","anthropic","google","vertex" 等值。可选在创建对象的构造参数中指定 protocol 的值（默认自动选择），但在创建对象以后不能再手动修改 protocol 属性。 ### webRestAiChatObject.afterToolCalling # ```aardio webRestAiChatObject.afterToolCalling = function(chatMessages){ /*每一次完成所有工具调用后回调此事件。 chatMessages 是即将回传到服务器的消息队列，调用代码可以缓存此对象以便在网络故障时恢复回传请求。返回 false 中止对话*/ return true; } ``` ### webRestAiChatObject.beforeToolCalling # ```aardio webRestAiChatObject.beforeToolCalling = function(){ /*每一次发起所有工具调用前回调此事件。返回 false 中止对话*/ return true; } ``` ### webRestAiChatObject.close() # 关闭对象释放资源 ### webRestAiChatObject.defaultHeaders # 替换所有请求默认添加的HTTP头请求结束时不会清空此属性该值可以是一个字符串,也可以是键值对组成的table对象 ### webRestAiChatObject.external # ```aardio webRestAiChatObject.external = { getWeather = function(args){ /* args 必须声明为对象。对参数 args 的修改 AI 可以看到，可能令 AI 困惑的修改应当先用 table.clone 复制副本。可返回任意数据类型、数组、对象（建议使用意图清晰的字段名）。更多示例可参考 autos.tools.handlers, autos.tools.schemas 库源码。 */ return {succeeded=succeeded;error=err;result=result;comment=comment} };/*external 表用于定义的 AI 可以调用的函数。用于支持 function calling 功能。创建 web.rest.aiChat 对象时，参数表必须通过 tools 字段声明允许被调用的函数。*/ } ``` ### webRestAiChatObject.extraHeaders # 设置每次请求都附加的 HTTP 请求头，可在构造参数表中指定初始值。此属性值可以是 web.joinHeaders 函数支持的字符串、表（数组、键值对） ### webRestAiChatObject.extraParameters # 指定附加到所有请求参数中的默认参数。该值应当是一个表,请求参数指定表对象时或为null才会附加 extraParameters。使用 Responses 协议时，input、instructions、store、stream、background、conversation、previous_response_id 为内部事务字段，不允许由附加参数覆盖。 ### webRestAiChatObject.extraUrlParameters # 指定附加到所有请求 URL 的默认参数。该值可以是一个表或字符串。表参数使用 inet.url.stringifyParameters 转换为字符串。表中的值如果是函数则每次请求都调用该函数取值 ### webRestAiChatObject.get(网址,参数表) # 使用该GET方法提交请求,获取资源请求参数将会自动转换为URL附加参数, 请求参数可以指定表或字符串,如果是表请求前会转换为字符串成功返回数据,失败返回空值,错误信息,错误代码 ### webRestAiChatObject.getText(msg) # 以非流式方式调用聊天会话接口，并仅返回最终回复的可见正文字符串。支持 OpenAI Chat Completions、OpenAI Responses、Anthropic、Google 与 Vertex。失败返回 null,错误信息,错误代码。 ### webRestAiChatObject.lastRequestUrl # 获取最后一次请求的 URL。允许的 beforeRequestHeaders 事件中修改此属性以改变请求地址。 ### webRestAiChatObject.lastResponse() # 获取最后一次服务器返回的数据，流式调用时此函数返回值无意义。如果控制台已打开或在开发环境中导入 console 库则在控制台输出数据下载文件时该值为空 ### webRestAiChatObject.lastResponseError() # 返回服务器最后一次返回的错误响应，并转换为错误对象。与调用 API 时转换响应数据一样，支持相同的服务器响应格式。如果错误来自本地（lastStatusCode 属性为 null）则此函数返回 null 。如果最后一次发生请求成功，则此函数返回 null 。如果在参数 @1 中指定返回字段，且错误对象包含该字段则使用直接下标获取并返回字段值。获取字段失败返回 null 而非抛出异常 ### webRestAiChatObject.lastResponseObject() # 获取最后一次服务器返回的对象（已将响应文本解析为对象），如果是 SSE 流式调用，返回最后一次接受的包含 token 计数的对象请求失败，或者下载文件时此属性值为空。 ### webRestAiChatObject.lastResponseString() # 获取最后一次服务器返回的原始数据，流式调用时此函数返回值无意义。请求失败，或者下载文件时此属性值为空 ### webRestAiChatObject.lastStatusCode # 获取最近一次请求返回的HTTP状态码 100 ~ 101 为信息提示 200 ~ 206 表示请求成功 300 ~ 305 表示重定向 400 ~ 415 表求客户端请求出错 500 ~ 505 表示服务端错误 ### webRestAiChatObject.lastStatusMessage() # 获取最近返回的HTTP状态码文本描述第二个返回值为状态码 ### webRestAiChatObject.listModels() # 返回接口支持的模型信息列表。有些服务端不支持这个接口。 ### webRestAiChatObject.messages # 调用聊天会话接口。 ### webRestAiChatObject.messages(msg) # 仅指用参数 @msg 指定聊天消息上下文（web.rest.aiChat.messages 对象），省略其他参数时则直接返回服务器响应的最终数据，返回值是解析 JSON 响应数据得到的表对象。失败返回 null, 错误信息,错误代码。非流式调用时不同协议返回的对象格式并不相同。改用 getText 方法可直接获取 AI 回复文本，兼容所有协议。 ### webRestAiChatObject.messages(msg,writeDelta,sendBackProtocol) # 调用聊天会话接口。 - 可选用参数 @msg 指定 web.rest.aiChat.messages 对象（这也是一个包含对话上下文的数组）。 - 可选用参数 @writeDelta 指定 AI 以流式回复时接收文本的回调函数。 * @writeDelta 函数的回调参数 @1 为文本时则应输出增量回复，回调参数为 null 时完成输出。 * @writeDelta 接收 null 参数时必须保证幂等性，不重复执行/无副作用 * @writeDelta 函数返回 false 停止接收回复。 * 如果不指定 @writeDelta 则函数直接返回最终结果（解析服务器回复 JSON 并返回表对象）。 - 可选用参数 @sendBackProtocol 指定上次中断交错工具链之前使用的协议类型，必须与当前 _protocol 。成功返回 true（或表对象），失败返回 null,错误信息,错误代码。流式调用返回 null,err,0 表示回复未完成但未发生其他错误，用户主动中止时应忽略 err。返回 null,"",0 表示流式传输没有收到回复正文（思考内容与工具调用除外） ### webRestAiChatObject.ok() # 最后一次请求是否成功服务器应答并且状态码为2XX该函数返回真 ### webRestAiChatObject.post(网址,参数表) # 使用该POST方法提交请求,新增或修改资源请求参数可以指定表或字符串,如果是表请求前会转换为字符串成功返回数据,失败返回空值,错误信息,错误代码 ### webRestAiChatObject.referer # 引用页地址。如果此属性指定了一个值，则每次请求都会使用该引用页。如果不指定，每次请求都会自动设置上次请求的网址为引用页。这个属性不像 inet.http 对象的 referer 属性那样每次请求结束都会清空。 ### webRestAiChatObject.setHeaders # 设置所有请求默认添加的HTTP头 ### webRestAiChatObject.setHeaders(headers) # 参数 @headers 必须指定一个表中, 用该表中的键值对更新 defaultHeaders 属性中的键值如果addHeaders的原属性值不是一个表,则先清空该属性 ### webRestAiChatObject.setTimeouts(连接超时,请求超时,接收超时) # 设置超时,以亳秒为单位（1秒为1000毫秒）。默认设置为连接超时=15000,请求超时=30000,接收超时=600000 ，适合非流式调用。对于流式调用建议显示修改为连接超时=15000,请求超时=30000,接收超时=60000 。流式接口接收间隔较短，并且通常有心跳保活措施，接收超时不宜过大。但部分模型将加密思考内容仅发送摘要间隔较慢，因此接收超时也不宜过小。 ## webRestAiChatObject 事件列表 # ### webRestAiChatObject.onDeltaToolCalling # ```aardio webRestAiChatObject.onDeltaToolCalling = function(toolCalls,finishReason){ /*自定义流式回复中的对 tool_calls 字段的处理方法，主要用于中转服务端。客户端一般不建议定义或使用此回调函数，用法请参考库源码 */ } ``` ### webRestAiChatObject.onToolCalling # ```aardio webRestAiChatObject.onToolCalling = function(name,args){ /*调用每个工具前回调此事件。 name 为工具名称，args 为参数（表对象）。返回 false 中止对话*/ return true; } ``` ### webRestAiChatObject.onToolCallingError # ```aardio webRestAiChatObject.onToolCallingError = function(err, name, args){ /*本地工具函数执行抛出异常/错误时回调此事件。 err 为错误信息，name 为工具名称，args 为调用参数。*/ } ``` ## webRestAiChatObject.config 成员列表 # 自定义的 API 配置表。默认指向创建对象时指定的表参数。 ### webRestAiChatObject.config.reasoning # 推理配置表。如果仅指定空表 `{}` 则启用推理模式。默认启用推理的模型可用 `{maxTokens=0}` 禁用推理。指定 maxTokens 字段可限制推理消耗的最大 tokens 。也可以通过 effort 字段指定 "high", "medium", 或 "low" 之一的值设置推理强度。这两个字段可以自动转换以兼容不同接口。注意不是所有大模型都支持此设置。