Descripción del artículo: AI Chat v2 conserva la forma sencilla de llamar a la interfaz de conversación original, al tiempo que incorpora entrada multimodal, flujos de eventos estructurados, llamadas automáticas a herramientas, pausa y reanudación, ejecución asíncrona y gestión de sesiones. Este artículo comienza con una migración que casi no requiere reescribir código y explica cómo estos cambios afectan al desarrollo real de productos.

Muchas interfaces de chat son muy fáciles de usar en la etapa de demostración: se pasa una pregunta, se espera a que el modelo devuelva un texto y luego se muestra el texto en la página.

Cuando el producto sigue avanzando, las cosas ya no se reducen a “preguntar una vez, responder una vez”. Los usuarios subirán PDF y capturas de pantalla, y el modelo necesitará buscar en la web, leer archivos e incluso llamar a herramientas ya autorizadas como GitHub y Notion. Una tarea puede durar varias rondas y, a mitad de camino, detenerse para pedir más información por falta de datos. En este momento, si la interfaz sigue devolviendo solo una cadena de texto en constante crecimiento, al frontend le resulta difícil saber qué está haciendo el modelo, y al backend también le resulta difícil determinar si la tarea realmente ha terminado.

Ace Data Cloud AI Chat v2 API resuelve precisamente este problema. No elimina la forma original de conversación, sino que, sobre la base de ser compatible con llamadas simples, divide una respuesta en eventos que los programas pueden reconocer y procesar: el contenido principal es contenido principal, las llamadas a herramientas son llamadas a herramientas, y las citas, archivos, errores y estado final tienen cada uno una posición clara.

Ace Data Cloud AI Chat v2: entrada multimodal, herramientas de Agent y flujo de eventos estructurado

Figura: AI Chat v2 ya no comprime toda la tarea en un fragmento de texto, sino que mantiene estructurados los eventos de entrada, herramientas y salida.

La migración puede comenzar cambiando una dirección

Si el proyecto está utilizando la versión anterior de /aichat/conversations, no es necesario reescribir primero la estructura de mensajes, ni crear antes una interfaz de Agent. V2 sigue aceptando campos como model, question, stateful, id, references y preset. La migración mínima solo requiere cambiar la dirección de la solicitud a:

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

Una solicitud básica sigue siendo muy corta:

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
  }'

En el modo JSON normal, la interfaz sigue devolviendo un resultado familiar:

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

Guarda el id devuelto y, en la siguiente solicitud, incluye el mismo id para poder continuar la conversación. stateful es true de forma predeterminada y se utiliza para controlar si se carga y continúa el contexto de la conversación guardada.

Este paso es muy adecuado para proyectos reales: primero se verifica si la autenticación, el modelo, la latencia y los negocios antiguos funcionan correctamente, y luego se incorporan gradualmente las nuevas capacidades. La migración no tiene que estar vinculada a la reconstrucción de la interfaz en el mismo lanzamiento.

Cuando los archivos y las imágenes entran en la conversación, el orden también se convierte en información

El anterior question es adecuado para texto puro. En tareas como “primero leer el informe, luego comparar con la captura de pantalla y finalmente dar una conclusión”, una simple lista de adjuntos ya no es lo bastante precisa. V2 añade un arreglo estructurado message, en el que se pueden colocar texto, imágenes y archivos en orden:

{
  "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"}
    }
  ]
}

Los bloques de contenido disponibles incluyen text, image_url y file_url. Lo importante no es solo “admitir adjuntos”, sino que la relación entre los contenidos no se pierde durante la transmisión. El cliente puede indicar claramente al modelo: qué fragmento es la instrucción de la tarea, qué documento es el material original y qué debe compararse a continuación.

Para permitir una migración fluida de clientes antiguos, V2 sigue reconociendo references. Las URL con extensiones de imagen se procesarán como imágenes, y las demás URL se procesarán como archivos. Si solo se actualiza la interfaz, se puede conservar temporalmente la forma de escritura original; si el orden de entrada afecta a la comprensión, se recomienda usar message.

La respuesta en streaming ya no consiste solo en “estar escribiendo”

La salida en streaming tradicional normalmente solo tiene incrementos de texto. Después de que el modelo comienza a buscar, leer archivos o llamar a herramientas externas, la página parece quedarse bloqueada, el usuario no sabe si la tarea continúa y el desarrollador tampoco puede obtener un estado claro.

AI Chat v2 proporciona tres formas de respuesta mediante el encabezado de solicitud accept:

Escenario de uso accept Forma de retorno
Solicitud simple del lado del servidor application/json Devuelve {answer, id} al finalizar
Node, Python, CLI o Worker application/x-ndjson Un evento JSON por línea
Frontend web text/event-stream Flujo de eventos SSE

En los modos NDJSON y SSE, lo que se devuelve no son solo tokens, sino un conjunto de eventos tipados. text_delta se utiliza para incrementos del contenido principal, tool_use indica que el modelo está preparado para llamar a una herramienta, tool_result devuelve el resultado de la herramienta, citation proporciona la fuente de la cita, card y artifact transportan tarjetas o productos que pueden mostrarse por separado, error indica que esta ronda ha fallado y done proporciona el uso y el motivo de finalización.

El siguiente consumidor de Python concatena el contenido principal mientras conserva los estados clave:

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))

Si el producto solo se preocupa por el texto final, basta con concatenar todos los text_delta.content; si se quiere crear una interfaz de Agent observable, se pueden renderizar por separado las llamadas a herramientas, las referencias, los resultados y los estados. Ambas necesidades utilizan la misma interfaz, sin necesidad de mantener dos conjuntos de protocolos para el “chat simple” y las “tareas complejas”.

Las llamadas a herramientas están disponibles de forma predeterminada, pero el producto aún debe delimitar claramente los límites

V2 puede permitir que el modelo llame a capacidades integradas como búsqueda web, extracción de páginas y lectura de archivos según las necesidades de la tarea; después de que el usuario conecte y autorice los servicios correspondientes, también puede utilizar herramientas MCP para procesar datos externos como GitHub y Notion.

En el flujo aparecerán por separado tool_use y tool_result, ambos se emparejan mediante tool_id. El frontend puede mostrar el progreso real basándose en esto, y el backend también puede registrar el tiempo de cada herramienta y los puntos de fallo.

Que las herramientas puedan llamarse automáticamente no significa que el ámbito de ejecución deba dejarse abierto sin límites. max_turns se utiliza para limitar el número de rondas de iteración del Agent en una solicitud; el rango indicado en la documentación es de 1—500; cuando se establece en 1, esta ronda solo realiza una llamada al modelo y no continúa con llamadas a herramientas. El entorno de producción debe configurarlo activamente según la complejidad de la tarea, el tiempo de respuesta y el presupuesto de costes, en lugar de depender durante mucho tiempo de un límite superior predeterminado elevado.

Para Webhook, CI/CD o tareas de monitorización, V2 admite async: true, las tareas pueden ejecutarse en segundo plano y obtener resultados mediante consultas o callback_url. Pero las acciones que implican enviar, publicar o escribir requieren una preautorización explícita mediante allowed_skills, allowed_mcp_servers o unattended_policy.

La conexión resuelve “si se puede acceder”, y la política de autorización resuelve “si en esta ocasión se puede actuar en nombre del usuario”. Estas dos cosas no pueden mezclarse.

Cuando al Agent le falta información, no es necesario fingir que la tarea ya se ha completado

Las tareas complejas suelen atascarse en cuestiones concretas: a qué canal publicar, qué formato adoptar, si sobrescribir archivos existentes. V2 proporciona para ello el evento ask_user_question. Después de que aparezca el evento, la sesión entra en un estado de espera de entrada del usuario.

El cliente guarda el id de la sesión actual y el tool_id correspondiente, muestra la pregunta y recopila la respuesta, y luego devuelve la respuesta mediante tool_results usando el mismo id de sesión, para que la tarea pueda continuar desde el punto de pausa. Este mecanismo también es adecuado para crear nodos de aprobación. En lugar de permitir que el modelo adivine por sí mismo cuando la información es insuficiente, es mejor devolver al usuario las decisiones que faltan.

La propia sesión también puede gestionarse

V2 añade un CRUD ligero de sesiones en el mismo endpoint, y distingue retrieve, retrieve_batch, update y delete mediante action.

retrieve_batch devuelve resúmenes sin incluir los messages completos, lo que resulta adecuado para la barra lateral de sesiones; cuando el usuario abre realmente una sesión, se llama de nuevo a retrieve para leer el contenido completo. Para las sesiones largas, la organización del contexto del lado del servidor tampoco sobrescribirá los mensajes originales guardados con resúmenes. Cuando sea necesario seguir modificando un artículo, verificar cifras o preparar una publicación, se debe seguir leyendo el texto original, en lugar de usar un resumen como sustituto del contenido completo.

Antes del lanzamiento, no verifiques solo “si se devuelve texto”

Después de integrar una interfaz de Agent, recibir texto parcial no significa que esta ronda se haya completado de forma fiable; que el flujo termine tampoco representa necesariamente que la tarea haya tenido éxito. El cliente debe procesar error y registrar usage y terminal_reason después de recibir done. En SSE, [DONE] solo indica el final de la transmisión y no puede sobrescribir los eventos de error que hayan aparecido anteriormente.

El API Token debe guardarse solo en el servidor; el analizador de flujos debe poder manejar fragmentos de red y eventos nuevos que temporalmente no reconoce; las llamadas a herramientas deben emparejarse mediante tool_id; los enlaces de referencias y los resultados deben renderizarse de forma segura; las conexiones con capacidad de escritura deben seguir conservando la confirmación humana o una autorización desatendida lo suficientemente limitada. Los nombres de los modelos, la facturación y las capacidades disponibles pueden actualizarse; al realizar la integración formal, se debe tomar como referencia la documentación actual, la página de servicio y la consola, y no dejar configuraciones de ejemplo codificadas de forma permanente.

Lo más digno de atención de AI Chat v2 no es añadir unos cuantos botones más a la ventana de chat. Permite por fin que las aplicaciones vean qué ocurre dentro de una tarea de IA: cuándo el modelo genera texto, cuándo llama a herramientas, dónde espera al usuario y con qué estado termina.

Si el proyecto actual todavía es solo un cuadro de preguntas y respuestas común, se puede empezar cambiando la dirección de la interfaz y seguir utilizando el cuerpo de solicitud original. Una vez que este paso sea estable, se pueden integrar message, NDJSON o SSE, la línea de tiempo de herramientas y la pausa y reanudación. La actualización puede ser pequeña, pero deja un espacio suficientemente grande para las futuras formas de producto.

Enlaces de referencia