Ganancias:
- Puede describir la estructura básica de una solicitud de API LLM (punto final, modelo, mensajes, max_tokens)
- Entiende la diferencia entre los roles de sistema, usuario y asistente y el historial de conversaciones sin estado.
- Puede leer e interpretar campos (bloques de contenido, stop_reason, uso) de la respuesta devuelta.
En módulos anteriores utilizamos inteligencia artificial desde una ventana de chat. Pero si desea incorporar IA en su propio producto, automatización o flujo de trabajo, una interfaz de chat no será suficiente; Debe conectarse al modelo mediante programación, es decir, con código o una herramienta de automatización. El nombre de este puente es API (Interfaz de programación de aplicaciones, el contrato que permite que dos software se comuniquen con ciertas reglas). Cuando termine esta unidad, sabrá qué constituye una solicitud de API LLM (modelo de lenguaje grande), qué funciones de mensaje realizan y cómo leer la respuesta. Esta es la base sobre la que se construirá el resto del módulo.
¿Cómo funciona la API?
El flujo básico en la API es el siguiente: envía una solicitud en un formato determinado; El servidor devuelve una respuesta en un formato específico. En los LLM, esto suele ser una llamada HTTP (HTTP: protocolo estándar para llevar solicitud-respuesta en la web) a una única dirección (punto final, la dirección fija en el servidor que maneja su solicitud). Por ejemplo, en una API de mensajería, todas las solicitudes van a una única dirección y se llevan en el cuerpo como JSON (notación de objetos JavaScript, un formato de texto que consta de pares clave/valor que pueden leer tanto humanos como máquinas).
En una solicitud, especifica al menos estas tres cosas:
- Modelo: qué modelo utilizará (por ejemplo, un modelo rápido y económico o un modelo potente).
- max_tokens: el número máximo de tokens (la unidad más pequeña en la que se procesa el texto, que se procesará en detalle en la siguiente unidad) que puede producir el modelo; es decir, límite de salida.
- mensajes: Lista de mensajes que componen la conversación.
Paso a paso: cómo configurar una solicitud
- Prepare el punto final y las credenciales. Agrega su clave API (la cadena secreta que prueba su identidad) a la solicitud en un encabezado. Nunca insertas la clave en el código; Cubriremos el almacenamiento seguro en la unidad 9.
- Seleccione el modelo y el límite de salida. Modelo liviano + max_tokens pequeños para una tarea sencilla; Modelo potente + límite mayor para una tarea compleja.
- Configure la lista de mensajes. List the system instruction, user message, and past rounds (if any).
- Envíe la solicitud y analice la respuesta. Lea el contenido del texto, el motivo de la detención y el uso del token del JSON devuelto.
Roles del mensaje: sistema, usuario, asistente
Una conversación consta de mensajes dispuestos en una secuencia y cada mensaje tiene una función. El rol determina cómo el modelo trata ese texto.
Rol
quien escribe
Propósito
sistema
Desarrollador/operador
Instrucciones permanentes, personalidad y reglas que se aplican durante toda la conversación.
usuario
usuario final
La pregunta o entrada actual del usuario.
asistente
modelo
Respuesta producida por el modelo (y respuestas anteriores)
La función del sistema está disponible como un campo de sistema separado en el cuerpo de la solicitud en la mayoría de los proveedores; El usuario y el asistente aparecen secuencialmente en la lista de mensajes. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Eres un asistente de soporte corporativo. Da una respuesta breve, formal y verificada. No inventes información de la que no estés seguro.", "messages": [ { "role": "user", "content": "¿Cómo inicio mi proceso de devolución?" } ]}
El discurso es apátrida
Este es el error más común: las llamadas a la API de LLM no tienen estado: el servidor no retiene memoria entre dos solicitudes. El modelo no recuerda tu solicitud anterior. Si estás configurando un chat de varias rondas, deberás reenviar rondas anteriores con cada nueva solicitud. La "memoria" del modelo consiste en una lista de mensajes que has enviado.
{ "modelo": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "usuario", "content": "Hola, mi nombre es Deniz". }, { "role": "asistente", "content": "Hola Deniz, ¿en qué puedo ayudarte?" }, { "role": "usuario", "content": "Acabo de decir mi nombre, ¿te acuerdas?" } ]}
Responder correctamente al tercer mensaje depende de que envíes los dos mensajes anteriores. Si no lo envías, el modelo no sabrá "Mar" y responderá incorrectamente. Esto también afecta directamente el costo: cuanto más larga es la conversación, mayor es la lista y cada solicitud consume más tokens.
Consejo: En conversaciones largas, resumir y mover rondas antiguas (resumen + últimas rondas) en lugar de enviar el historial completo reduce el costo y preserva la ventana de contexto. Profundizaremos en esto en las unidades 6 y 11.
Lea la respuesta
Cuando el modelo devuelve una respuesta, recibe un objeto estructurado, no texto sin formato. Zonas típicas:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Para iniciar una devolución, vaya a la página 'Mis pedidos' en su cuenta..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- contenido: La respuesta misma; Es una lista de bloques de contenido. El campo de texto del bloque de texto es la respuesta real.
- stop_reason: Por qué se detuvo el modelo. end_turn = final natural; max_tokens = atascado en el límite de salida (la respuesta puede estar incompleta); rechazo = rechazado por razones de seguridad. Su código siempre debe mirar primero stop_reason.
- uso: Números de token de entrada y salida. Es la base del seguimiento de costos y límites.
Atención: si stop_reason es max_tokens, la respuesta no se completa. Tratar esto como una "respuesta exitosa" y mostrar la mitad del texto al usuario es uno de los errores más comunes en producción. Aumente max_tokens o use streaming.
Aviso débil / Aviso fuerte
Misma tarea con dos indicaciones del sistema diferentes:
# DÉBIL Eres un asistente. Responde a las preguntas.
# FUERTEEres un asistente de soporte corporativo. Reglas: - Confiar únicamente en la información del documento de política proporcionado; Si no está en el documento, diga "No tengo esta información, la dirijo a la unidad correspondiente". - Las respuestas no deben exceder las 3 frases, ser formales y claras. - No pedir datos personales (número de identificación TC, número de tarjeta) y no repetir. - No adivines cuando no estés seguro.
Versión potente; Define alcance, forma, margen de seguridad y comportamiento en incertidumbre. La coherencia del resultado del modelo proviene directamente de esta claridad.
Tres mini estuches
Caso 1: Bot de soporte (trampa de apatridia). Un equipo de comercio electrónico puso en funcionamiento el bot; Cuando el usuario dijo "cancelar el pedido anterior", el robot "olvidó" el número de pedido. Motivo: enviaban cada solicitud solo con el último mensaje. Solución: agregaron las últimas 6 rondas a la lista de mensajes. Resultado: contexto preservado, pero la entrada por solicitud aumentó de 40 tokens a ~600 tokens; cubriremos la lección de costos en la unidad 2.
Caso 2: Resumen del contrato incompleto. Un equipo legal estaba delineando contratos de 10 páginas; max_tokens: 300 seguían siendo bajos, los resúmenes se cortaban a mitad de la frase. stop_reason era max_tokens cada vez pero nadie miraba. se aumentó max_tokens a 1500 y se agregó la verificación stop_reason; La tasa resumida truncada disminuyó del 18% al 0%.
Caso 3: Mezcla de roles. Un equipo de marketing estaba escribiendo todas las instrucciones en el mensaje del usuario, dejando el sistema en blanco. Cuando la entrada del usuario se mezclaba con instrucciones, el modelo a veces cumplía con la orden del usuario de "olvidar las reglas anteriores". Trasladaron reglas permanentes al sistema; Al separar las aportaciones del usuario de las instrucciones, las infracciones de las reglas disminuyeron significativamente.
Errores comunes
- Olvidarse de enviar el pasado: Se piensa que el modelo "no recuerda"; mientras que es apátrida. Tú llevas el contexto.
- Sin mirar `stop_reason`: la respuesta detenida con max_tokens se considera completa.
- Incrustar la instrucción en `usuario`: reglas persistentes en el sistema; la entrada instantánea va al usuario. La mezcla crea vulnerabilidades de seguridad.
- Confundir `contenido` con una cadena simple: la respuesta es una lista de bloques; lea el campo de texto del primer bloque de texto, verifique su tipo antes de obtener contenido [0] con un índice ciego.
- Incrustar la clave en el código: utilice una variable de entorno (unidad 9).
Más profundo: bloques de contenido y respuestas de varias partes
Comprender por qué el campo de contenido de la respuesta es una lista es fundamental para las funciones avanzadas que encontrará más adelante. A veces el modelo devuelve no un solo bloque de texto, sino varios bloques: un bloque de pensamiento, seguido de un bloque de texto; o un bloque de texto seguido de un bloque de uso de herramientas. Es por eso que contar ciegamente el contenido [0] como una "respuesta" es frágil. El enfoque correcto es revisar la lista y ordenarla por tipo: recopila el contenido de texto de los bloques cuyo campo de tipo es texto y trata otros tipos (pensamiento, herramienta) por separado.
Lo que hace esta distinción en la práctica es que puede registrar el razonamiento del modelo (si lo hay) sin revelarlo al usuario, redirigir las llamadas a la herramienta a una lógica separada y solo imprimir la respuesta real en la pantalla. A medida que avance el módulo (especialmente en las unidades 4 y 11), verá cuán útil es esta estructura de bloques para validar y dirigir la salida.
Otro punto práctico: puedes acceder al mismo modelo desde diferentes plataformas de proveedores (API directa, a través de un proveedor en la nube). Aunque la dirección del punto final y el formato de autenticación pueden cambiar, conceptos básicos como las funciones de los mensajes, la apatridia y la estructura de respuesta siguen siendo los mismos. Por lo tanto, los conceptos básicos de esta unidad se aplican sin importar la plataforma que utilice.
En resumen
Una solicitud de API LLM consta del modelo, el límite de salida y la lista de mensajes; Los roles (sistema, usuario, asistente) determinan el comportamiento del modelo. Las llamadas no tienen estado: usted lleva el contexto con cada solicitud. La respuesta es un objeto estructurado; Leer e interpretar los campos content, stop_reason y use es la base de la durabilidad en producción.
Tarea de aplicación
Elija una tarea de su propia profesión (por ejemplo, clasificar el correo electrónico entrante, crear resúmenes breves). En una hoja de papel: (1) escriba el mensaje del sistema con 4-5 reglas, (2) configure un mensaje de usuario de muestra y un historial de 2 rondas, si corresponde, (3) determine un valor razonable para max_tokens y escriba la justificación, (4) enumere qué valores stop_reason manejará en la respuesta devuelta y cómo.
lista de verificación
- [] Puedo contar las tres partes obligatorias de una solicitud (modelo, max_tokens, mensajes).
- [] Puedo explicar la diferencia entre los roles de sistema, usuario y asistente.
- [] Sé que las llamadas no tienen estado y que necesito llevar el pasado.
- Puedo leer y comentar sobre [] contenido, stop_reason y campos de uso.
- [] Con max_tokens puedo notar y manejar la respuesta truncada.