Cómo se hablan los programas en una red
HTTP es la forma en que dos programas se hablan por una red: uno envía una petición y el otro devuelve una respuesta. JSON es el formato de texto que suelen usar para los datos.
Toda API de modelos funciona así. Cuando sabes leer una petición y una respuesta, puedes usarlas todas.
Al final de esta lección
Nota
Puedo leer y escribir una petición HTTP y un cuerpo JSON.
Palabras clave
| Palabra | Qué significa | Ejemplo |
|---|---|---|
| Petición | lo que un programa envía para pedir algo | |
| Respuesta | lo que vuelve como contestación a una petición | |
| Cabecera | un dato con nombre sobre una petición o una respuesta | content-type |
| Código de estado | un número que dice cómo fue la petición | 200 |
| JSON | un formato de texto para datos hechos de claves y valores |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Una petición tiene cuatro partes
El método dice qué hacer: GET lee y POST envía datos. La URL dice dónde. Las cabeceras añaden detalles, como el tipo de los datos. El cuerpo son los datos mismos.
Una API de modelos recibe un POST con un cuerpo JSON que contiene tus mensajes.
Ejemplo resuelto: una petición, parte por parte
| Parte | Qué contiene | En nuestra llamada |
|---|---|---|
| Método | Qué hacer | POST |
| URL | Adónde enviarla | http://ai:4000/v1/chat/completions |
| Cabecera | El tipo del cuerpo | content-type: application/json |
| Cuerpo | Los datos, en JSON | model, messages, max_tokens |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Imprime la petición que enviaría un script
docker exec -w /home/node/project agent node -e "const body={model:'lab',messages:[{role:'user',content:'Saluda'}],max_tokens:20};console.log('POST /v1/chat/completions');console.log('content-type: application/json');console.log(JSON.stringify(body,null,2))"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
JSON es texto con claves y valores
JSON escribe los datos como texto. Un objeto son llaves con pares "clave": valor. Una lista va entre corchetes. Las claves van siempre entre comillas dobles.
Tu programa convierte los datos en texto JSON para enviarlos (JSON.stringify) y el texto JSON en datos para leerlos (JSON.parse).
Una respuesta tiene un estado y un cuerpo
Lo primero de una respuesta es el código de estado. Un número de 200 a 299 significa que funcionó. Un número de 400 a 499 significa que la petición tenía un fallo. Un 500 o más significa que el fallo era del servicio.
Lee el estado antes de leer el cuerpo.
Ejemplo resuelto: códigos de estado habituales
| Estado | Significado | Qué haces |
|---|---|---|
| 200 | Funcionó | Leer el cuerpo |
| 400 | La petición es incorrecta | Corregir el cuerpo |
| 401 | Falta la clave o es errónea | Revisar la clave |
| 403 | No permitido | Leer el mensaje |
| 429 | Demasiadas peticiones | Esperar y reintentar |
| 503 | Aún no está listo | Reintentar más tarde |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Llama a un modelo y lee el estado
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';const show=(s,t,k,m)=>{console.log('Estado: '+s);console.log('Tipo de contenido: '+t);console.log('Claves de primer nivel: '+k);console.log('Respuesta: '+m)};(async()=>{try{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify({model:'lab',messages:[{role:'user',content:'Saluda en tres palabras.'}],max_tokens:20})});const j=await r.json();if(r.ok===false)throw new Error(r.status+' '+j.error.message);show(r.status,r.headers.get('content-type'),Object.keys(j).join(', '),j.choices[0].message.content)}catch(e){console.log('Sin respuesta ('+e.message+'). Muestra grabada:');show(200,'application/json','id, object, model, choices, usage','Hola, buen amigo.')}})()"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Un error frecuente
Advertencia
Mucha gente cree que el estado 200 significa que la respuesta es correcta. Solo significa que la petición funcionó. Un modelo puede devolver 200 con una respuesta equivocada o rara. Mira primero el estado y después el contenido.
Para ir más lejos: cambia la petición
Modifica la ejecución que imprime la petición. Añade temperature: 0 al cuerpo y ejecútala otra vez. Después cambia max_tokens a 5.
Apunta cada vez qué parte cambiaste: el método, la URL, una cabecera o el cuerpo.