文章说明:AI Chat v2 保留原有对话接口的简单调用方式,同时加入多模态输入、结构化事件流、自动工具调用、暂停与恢复、异步执行和会话管理。本文从一次几乎不用重写代码的迁移开始,讲清楚这些变化如何影响真实的产品开发。

很多聊天接口在演示阶段都很好用:传入问题,等模型返回一段文字,再把文字显示在页面上。

产品继续往前走,事情就不再只是“问一句、答一句”。用户会上传 PDF 和截图,模型需要查网页、读文件,甚至调用已经授权的 GitHub、Notion 等工具。一次任务可能持续好几轮,中途还会因为缺少信息停下来追问。此时,如果接口仍然只返回一串不断增长的文本,前端很难知道模型正在做什么,后端也难以判断任务究竟结束了没有。

Ace Data Cloud AI Chat v2 API 解决的正是这个问题。它没有推翻原来的对话方式,而是在兼容简单调用的基础上,把一次回答拆成程序可以识别和处理的事件:正文是正文,工具调用是工具调用,引用、文件、错误和最终状态各自有明确的位置。

Ace Data Cloud AI Chat v2:多模态输入、Agent 工具与结构化事件流

图:AI Chat v2 不再把整个任务压成一段文本,而是让输入、工具和输出事件保持结构。

迁移可以先从改一个地址开始

如果项目正在使用旧版 /aichat/conversations,不必先重写消息结构,也不用先做一套 Agent 界面。V2 继续接受原有的 model、question、stateful、id、references 和 preset 等字段。最小迁移只需要把请求地址改成:

https://api.acedata.cloud/aichat2/conversations

一个最基础的请求仍然很短:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "YOUR_SUPPORTED_MODEL",
    "question": "请概括这份需求里最重要的三个问题。",
    "stateful": true
  }'

普通 JSON 模式下,接口仍返回熟悉的结果:

{
  "answer": "...",
  "id": "conversation-uuid"
}

保存返回的 id,下一次请求带上同一个 id,便可以继续对话。stateful 默认是 true,用于控制是否加载并延续已保存会话的上下文。

这一步很适合真实项目:先验证鉴权、模型、延迟和旧业务是否正常,再逐步接入新能力。迁移不必和界面重构绑在同一次上线里。

当文件和图片进入对话,顺序也成了信息

旧版 question 适合纯文本。到了“先看报告,再对照截图,最后给结论”这种任务,简单的附件列表就不够精确了。V2 增加了结构化 message 数组,可以按顺序放入文本、图片和文件:

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "阅读报告,并把其中的趋势与后面的仪表盘截图进行对照。"
    },
    {
      "type": "file_url",
      "file_url": {"url": "https://example.com/report.pdf"}
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/dashboard.png"}
    }
  ]
}

可用内容块包括 text、image_url 和 file_url。重要的并不只是“支持附件”,而是内容之间的关系没有在传输时丢失。客户端能够明确告诉模型:哪一段是任务说明,哪一份是原始材料,接下来又该比较什么。

为了让旧客户端平滑迁移,V2 仍然识别 references。图片扩展名对应的 URL 会按图片处理,其他 URL 会按文件处理。如果只是升级接口,可以暂时保留原写法;如果输入顺序会影响理解,建议改用 message。

流式响应不再只有“正在打字”

传统流式输出通常只有文本增量。模型开始搜索、读取文件或调用外部工具后,页面看起来像卡住了,用户不知道任务是否继续,开发者也拿不到清楚的状态。

AI Chat v2 通过 accept 请求头提供三种响应方式:

使用场景 accept 返回方式
简单服务端请求 application/json 完成后返回 {answer, id}
Node、Python、CLI 或 Worker application/x-ndjson 每行一个 JSON 事件
Web 前端 text/event-stream SSE 事件流

在 NDJSON 和 SSE 模式中,返回的不只是 token,而是一组有类型的事件。text_delta 用于正文增量,tool_use 表示模型准备调用工具,tool_result 返回工具结果,citation 提供引用来源,card 和 artifact 承载可单独展示的卡片或产物,error 表示本轮失败,done 给出用量和终止原因。

下面的 Python 消费端一边拼接正文,一边保留关键状态:

import json
import os
import requests

url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
    "accept": "application/x-ndjson",
    "authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
    "content-type": "application/json",
}
payload = {
    "model": os.environ["ACEDATA_CHAT_MODEL"],
    "question": "检索资料,给出带来源的简要结论。",
    "stateful": True,
}

with requests.post(url, json=payload, headers=headers,
                   stream=True, timeout=120) as response:
    response.raise_for_status()
    answer = []
    for raw_line in response.iter_lines():
        if not raw_line:
            continue
        event = json.loads(raw_line)
        event_type = event.get("type")
        if event_type == "text_delta":
            answer.append(event.get("content", ""))
        elif event_type == "tool_use":
            print("开始调用:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("工具是否失败:", event.get("is_error"))
        elif event_type == "error":
            raise RuntimeError(event.get("message", "未知错误"))
        elif event_type == "done":
            print("用量:", event.get("usage"))
            print("终止原因:", event.get("terminal_reason"))

print("".join(answer))

如果产品只关心最终文字,把所有 text_delta.content 拼接起来即可;如果要做可观察的 Agent 界面,就可以把工具调用、引用、产物和状态分别渲染。两种需求使用同一个接口,不必为“简单聊天”和“复杂任务”维护两套协议。

工具调用默认可用,但产品仍要画清边界

V2 可以让模型按任务需要调用网页搜索、页面提取和文件读取等内置能力;用户连接并授权相应服务后,也可以使用 MCP 工具处理 GitHub、Notion 等外部数据。

流中会分别出现 tool_use 和 tool_result,两者通过 tool_id 配对。前端可以据此显示真实进度,后端也能记录每次工具耗时和失败位置。

工具能自动调用,并不意味着执行范围应该无限放开。max_turns 用于约束一次请求中的 Agent 迭代轮数,文档给出的范围是 1—500;设置为 1 时,本轮只进行一次模型调用,不会继续进入工具调用。生产环境应结合任务复杂度、响应时间和成本预算主动设置,而不是长期依赖较大的默认上限。

对于 Webhook、CI/CD 或监控任务,V2 支持 async: true,任务可以在后台执行,并通过查询或 callback_url 获取结果。但涉及发送、发布、写入的动作,需要通过 allowed_skills、allowed_mcp_servers 或 unattended_policy 明确预授权。

连接解决的是“能不能访问”,授权策略解决的是“这一次可不可以代替用户行动”。这两件事不能混在一起。

Agent 缺少信息时,不必假装任务已经完成

复杂任务经常卡在具体问题上:发布到哪个频道、采用哪种格式、是否覆盖已有文件。V2 为此提供 ask_user_question 事件。事件出现后,会话进入等待用户输入的状态。

客户端保存当前会话的 id 和对应 tool_id,展示问题并收集答案,再用同一个会话 id,通过 tool_results 把回答交回去,任务便可以从暂停点继续。这个机制也适合做审批节点。与其让模型在资料不足时自行猜测,不如把缺失的选择交还给用户。

会话本身也可以管理

V2 在同一个端点中加入了轻量的会话 CRUD,通过 action 区分 retrieve、retrieve_batch、update 和 delete。

retrieve_batch 返回摘要而不包含完整 messages,适合会话侧边栏;用户真正打开会话时,再调用 retrieve 读取正文。对于长会话,服务端的上下文整理也不会用摘要覆盖已保存的原始消息。需要继续修改文章、核对数字或准备发布时,仍应读取原文,而不是拿摘要代替正文。

上线前,别只验证“有没有文字返回”

接入 Agent 接口之后,收到部分文本不等于本轮已经可靠完成;流结束也不一定代表任务成功。客户端应处理 error,并在收到 done 后记录 usage 和 terminal_reason。在 SSE 中,[DONE] 只表示传输结束,不能覆盖此前已经出现的错误事件。

API Token 应只保存在服务端;流解析器要能处理网络分块和暂时不认识的新事件;工具调用应按 tool_id 配对;引用链接和产物要安全渲染;可写连接继续保留人工确认或足够窄的无人值守授权。模型名称、计费与可用能力可能更新,正式接入时应以当前文档、服务页和控制台为准,不要把示例配置长期写死。

AI Chat v2 最值得关注的地方,并不是让聊天窗口再多几个按钮。它让应用终于能看见一次 AI 任务内部发生了什么:模型何时输出文字,何时调用工具,在哪里等待用户,又以什么状态结束。

如果现有项目还只是普通问答框,可以先改接口地址,继续使用原来的请求体。等这一步稳定后,再接入 message、NDJSON 或 SSE、工具时间线和暂停恢复。升级可以很小,但它为后面的产品形态留出了足够大的空间。

参考链接