Integrar una API compatible amb OpenAI pot semblar senzill: només cal canviar la URL base i la clau d'API. No obstant això, en entorns empresarials on es desenvolupen aplicacions a mida, la validació inicial és crítica per evitar errors costosos. Una prova de fum (smoke test) permet verificar en pocs segons si l'autenticació, el model i la infraestructura de xarxa funcionen correctament, sense assumir que tot està bé només perquè el codi compila. Aquest article explica com realitzar aquesta validació pas a pas, amb un enfocament pràctic i orientat al diagnòstic de problemes reals, com els que trobem en projectes d'IA i ciberseguretat.
A Q2BSTUDIO, empresa especialitzada en desenvolupament de programari i tecnologia, sabem que una mala configuració inicial pot provocar hores de depuració innecessàries. Per això recomanem aïllar les variables: no toquis el model, el temps d'espera ni el prompt fins que la connexió bàsica estigui confirmada. La prova de fum es compon de tres fases: 1) verificar autenticació i URL base; 2) descobrir els models disponibles des del compte actual; 3) enviar una petició de generació mínima amb reintents desactivats. Cada fase respon una pregunta concreta i evita la temptació de canviar-ho tot alhora.
El primer pas és externalitzar la configuració. Guarda la clau API i la URL base en variables d'entorn, mai al codi font. Per exemple, exporta DAOXE_API_KEY i DAOXE_BASE_URL. No incloguis encara el nom del model; aquest pot variar segons el compte i canviar amb el temps. Copiar un model d'un tutorial antic introdueix una variable innecessària abans de saber si l'autenticació funciona. En entorns de núvol com AWS o Azure, utilitza el gestor de secrets de la plataforma. Això s'alinea amb les millors pràctiques de cloud AWS/Azure que apliquem als nostres projectes de transformació digital.
La segona fase consisteix a consultar l'endpoint /models mitjançant cURL o una eina similar. Aquesta petició no consumeix crèdits de facturació i retorna la llista de models als quals el compte té accés. Executa: curl --silent --show-error --fail-with-body '${DAOXE_BASE_URL}/models' -H 'Authorization: Bearer ${DAOXE_API_KEY}'. Si tens instal·lat jq, redueix la resposta als IDs dels models: curl ... | jq -r '.data[].id'. Copia exactament un d'aquests IDs i assigna'l a DAOXE_MODEL. Aquest pas descarta problemes de permisos, bloquejos regionals i errors a la URL base. Especialment rellevant quan es treballa amb agents IA que requereixen models específics, ja que un model no disponible provocarà fallades intermitents.
La tercera fase materialitza una petició de xat amb un prompt mínim: 'Reply with only OK.' i max_tokens limitat a 8. Utilitza el SDK oficial d'OpenAI (o qualsevol SDK compatible) amb maxRetries: 0. A Node.js, el codi seria:
import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env.DAOXE_API_KEY, baseURL: process.env.DAOXE_BASE_URL, timeout: 30000, maxRetries: 0 }); const response = await client.chat.completions.create({ model: process.env.DAOXE_MODEL, messages: [{ role: 'user', content: 'Reply with only OK.' }], max_tokens: 8 }); console.log(response);
Executa el script amb node smoke-test.mjs. Si la petició falla, obtindràs un error amb codi HTTP i missatge. Si té èxit, veuràs el contingut generat, el model retornat i l'ús de tokens. Aquest resultat prova que, en aquell instant, la combinació de runtime, xarxa, clau, model i SDK funciona. No prova disponibilitat a llarg termini, qualitat de sortida ni cost total, però proporciona una línia base fiable.
El diagnòstic capa a capa és clau. Si obtens un 401, la clau és invàlida o té espais; reintrodueix la clau de forma segura. Un 403 indica problemes de permisos regionals o de compte; revisa els termes del servei i no intentis saltar-te restriccions al codi. Un 404 suggereix que la URL base és incorrecta o que s'ha concatenat malament la ruta. Un error 'model not found' indica que l'ID no correspon a la llista actual; repeteix la fase 2. Un 429 implica que has superat la quota o la taxa; analitza les capçaleres de resposta abans de decidir una política de backoff. Errors de timeout o xarxa (DNS, TLS, proxy) es resolen executant la petició des del mateix entorn per separar problemes de xarxa dels de generació. Els errors 5xx solen ser temporals; guarda la marca de temps i reintenta més tard.
Des d'una perspectiva empresarial, aquesta metodologia encaixa perfectament en pipelines de CI/CD. A Q2BSTUDIO, dividim la integració contínua en dos nivells: les sol·licituds de canvi normals executen proves estàtiques i contractes simulats sense clau real; un job protegit i disparat manualment executa la prova de fum real amb secrets i un límit d'execució estricte. Això assegura que els canvis al codi no trenquin la connectivitat sense incórrer en costos d'API a cada commit. A més, al no imprimir la clau als registres, es reforça la ciberseguretat de tot el procés.
Un cop la ruta mínima funciona, es poden afegir reintents controlats, streaming, crides a eines i concurrència. Però l'ordre importa: cada capa s'ha de verificar abans d'apilar més complexitat. També és recomanable registrar el resultat de la prova de fum en un sistema de monitoratge, incloent timestamp, entorn, codi HTTP, temps de resposta, model retornat i ús de tokens. Mai incloguis la clau ni la capçalera d'autorització completa.
Aquest enfocament no només s'aplica a serveis com DaoXE, sinó a qualsevol endpoint compatible amb OpenAI. La seqüència reutilitzable és: separar configuració del codi, consultar l'endpoint de models, copiar un ID exacte, enviar una petició acotada sense reintents, registrar el resultat sense credencials. Si després necessites integrar BI / Power BI per visualitzar mètriques d'ús de l'API, o automatitzar fluxos amb automatització, tenir una base validada redueix significativament el temps de posada en producció.
En resum, la prova de fum per a una API compatible amb OpenAI és una pràctica senzilla però poderosa. Estalvia hores de depuració, evita costos innecessaris i proporciona confiança abans d'escalar a peticions més complexes. A Q2BSTUDIO, integrem aquest tipus de validacions en tots els nostres projectes de desenvolupament d'aplicacions a mida, cloud i ciberseguretat, garantint que la base de la comunicació amb els models d'IA sigui sòlida des del primer moment.
