Al construir una aplicación con LangChain, el primer paso no suele ser escribir una cadena, sino emparejar bien la clave. Con el mismo código, a unas personas les funciona en local y reciben un 401 después de desplegar; otras dejan la clave escrita en un notebook y olvidan limpiarla. La mayoría de los problemas no está en el framework, sino en el origen de la clave, el orden de carga y los límites de permisos.

Este artículo explica cómo gestionar las claves de API en un proyecto LangChain siguiendo el orden «origen—configuración—aislamiento—rotación—diagnóstico». Los modelos, las cuotas y los precios concretos se rigen por la página de precios de modelos y por la documentación del proveedor que uses.

Nota: LangChain es una marca de LangChain, Inc. Este artículo solo describe una configuración técnica y no tiene afiliación ni relación de cooperación con LangChain, Inc.; el comportamiento de cada paquete de integración puede cambiar según la versión, así que consulta la documentación correspondiente.

1. Primero, una distinción: LangChain no emite claves de modelo

LangChain es un framework de código abierto para desarrollar aplicaciones: se encarga de organizar modelos, herramientas, recuperación y flujos. Por lo general no incluye una cuota de llamadas a modelos, por lo que no existe una «clave de modelo de LangChain». Las credenciales que escribes en LangChain pertenecen en realidad al proveedor del modelo, a la plataforma en la nube o a la pasarela de IA.

En un proyecto suele haber al menos tres tipos de credenciales, con usos completamente distintos:

Credencial Uso Dónde se obtiene
Clave de API del modelo Llamar a modelos de chat, razonamiento o embeddings Consola del proveedor o de la pasarela de IA
LANGCHAIN_API_KEY Trazabilidad y evaluación con LangSmith LangSmith; solo se necesita si activas la observabilidad
Credenciales de nube Acceder a modelos alojados o recursos de nube Consola de control de acceso del proveedor cloud

Mezclar los tres tipos en una sola clave da como resultado permisos demasiado amplios y una rotación difícil. Sepáralos por uso antes de hablar de configuración.

2. Variables de entorno: convención predeterminada y paso explícito

ChatOpenAI de langchain-openai lee OPENAI_API_KEY de forma predeterminada, y los endpoints compatibles con OpenAI se indican con el parámetro base_url. La configuración mínima funcional es esta:

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

# Lee el .env cercano al proyecto; en producción conviene usar variables del sistema o un gestor de secretos
load_dotenv()

llm = ChatOpenAI(
    model=os.environ["ZSQH_MODEL"],       # El ID del modelo se consulta en la página de precios
    api_key=os.environ["ZSQH_API_KEY"],   # También se puede usar OPENAI_API_KEY por defecto
    base_url="https://ai.zhongshangqihang.com/v1",
    temperature=0,
)

print(llm.invoke("Explica en una frase qué es una pasarela de API").content)

Hay varios detalles que se pasan por alto con facilidad:

  • Las variables de entorno se leen al crear el objeto cliente, no al importar el módulo. Si asignas os.environ a mitad de un notebook, debes volver a crear la instancia de ChatOpenAI.
  • Pasar una cadena vacía de forma explícita anula la variable de entorno. Al diagnosticar un 401, revisa si queda algún api_key="" en el código.
  • Cada paquete de integración lee nombres de variables distintos; Anthropic y Google tienen sus propias convenciones, así que consulta la documentación correspondiente.
  • init_chat_model permite crear modelos de distintos proveedores de forma unificada, pero los parámetros adicionales y las variables predeterminadas siguen dependiendo de la integración subyacente; vuelve a validar después de actualizar.

3. .env y SecretStr: dos defensas en desarrollo local

Usar .env en local es cómodo, pero exige dos disciplinas.

Primera: .env nunca entra en el control de versiones. Añádelo a .gitignore al inicializar el proyecto y commitear también un .env.example sin valores reales para que las nuevas incorporaciones sepan qué variables necesitan. Si se llegó a subir por error, borrar el archivo no elimina el historial: revoca la clave de inmediato y después trabaja sobre el historial del repositorio.

Segunda: conoce SecretStr de LangChain. Los campos de clave de ChatOpenAI suelen guardarse como SecretStr, de modo que al imprimir el objeto o escribir logs aparecen enmascarados en lugar de en texto plano. Eso evita algunas salidas accidentales, pero no impide llamar a get_secret_value(), construir cabeceras a mano o imprimir la solicitud completa dentro de una excepción. No confundas «el framework enmascara» con «puedo registrar lo que quiera».

En despliegues con contenedores no escribas la clave dentro de la imagen: los parámetros de compilación y las capas pueden conservarse. Es preferible inyectarla en tiempo de ejecución mediante variables de entorno o un gestor de secretos.

4. Varios proveedores y modelos: ¿una clave o varias?

La respuesta depende de si la entrada está unificada. Con una pasarela de IA suele bastar una clave para llamar a varios modelos, que se distinguen con el parámetro model; si te conectas directamente a varios fabricantes, normalmente necesitarás una clave por cada uno.

Conviene dar nombres legibles a las variables y fijarlos en el equipo:

  • Para pasarelas: ZSQH_API_KEY y ZSQH_BASE_URL.
  • Para fabricantes: los nombres que exija el paquete de integración, como ANTHROPIC_API_KEY o GOOGLE_API_KEY.
  • Sufijos de entorno: _DEV, _STAGING, _PROD, para evitar que una clave de prueba llegue a producción.

Varios modelos implican también respaldo (fallback) y enrutamiento. LangChain puede usar .with_fallbacks() para cambiar a un modelo alternativo si falla el principal, pero el alternativo también necesita su propia configuración de autenticación. No supongas que «una misma clave sirve para todos los modelos»: una pasarela puede tener una lista permitida y una clave de fabricante puede estar limitada a ciertos modelos. Los ID disponibles se consultan en la página de precios de modelos.

5. Permisos mínimos: dividir claves por entorno y uso

El objetivo de la gestión de claves no es «tener las menos posibles», sino «tener límites lo más claros posible». Prácticas aplicables:

  • Usa una clave distinta para desarrollo, preproducción y producción; la de producción no debe estar en el equipo de ninguna persona desarrolladora.
  • Una clave por aplicación y por miembro del equipo; prohíbe el uso compartido.
  • Asigna un presupuesto menor a las claves de prueba y limita los modelos disponibles.
  • Activa todas las opciones de lista de IP, alertas de cuota o lista de modelos que ofrezca la consola.
  • En logs, tickets y capturas de pantalla conserva solo los últimos caracteres de la clave.

Si la pasarela permite medir el uso por clave, esa clave sirve a la vez para imputar costos y localizar fallos; una «clave universal» compartida hace imposible atribuir una factura anómala.

6. Rotación y revocación: crear, cambiar el tráfico, revocar

Se recomienda rotar al menos cada 90 días y hacerlo de inmediato si una persona deja el equipo, se pierde un dispositivo, se filtra una configuración o hay sospecha de exposición. El orden no debe invertirse:

  1. Crea la nueva clave en la consola con la fecha o la versión en el nombre, por ejemplo prod-app-202610.
  2. Escribe la nueva clave en el gestor de secretos o en las variables del entorno de despliegue.
  3. Reinicia o vuelve a desplegar la aplicación y confirma que el nuevo proceso cargó el valor.
  4. Envía una solicitud real para comprobar que el modelo responde y que el uso se registra en la nueva clave.
  5. Observa durante un tiempo para confirmar que no quedan instancias antiguas llamando.
  6. Cuando esté confirmado, revoca la clave anterior y actualiza el registro interno.

Si la clave se lee desde variables de entorno, la rotación normalmente no exige cambiar código, pero sí reiniciar o hacer un despliegue progresivo. Las conexiones persistentes o los procesos de larga duración pueden seguir usando la clave anterior; confirma que todas las instancias se reemplazaron antes de revocar.

7. CI y trabajo en equipo: que la clave no llegue a los logs

El entorno de CI combina ejecución automática y conservación de logs, por lo que es una zona de alto riesgo de filtración. Algunas reglas básicas:

  • Guarda la clave en los secretos cifrados de la plataforma de CI, nunca en texto plano dentro del archivo de la tubería.
  • Desactiva las opciones de depuración que repiten comandos, para que set -x no imprima las cabeceras de la solicitud.
  • Crea una clave específica para CI, con cuota baja y modelos limitados.
  • Usa herramientas de escaneo de secretos antes de cada commit y bloquea el envío si aparece una clave sospechosa.
  • En la revisión de código, trata .env, los archivos de configuración y las instantáneas de pruebas como archivos sensibles.

El documento de traspaso del equipo debe indicar el responsable de cada clave, su uso, la fecha de creación, la próxima fecha de rotación y el procedimiento de revocación en caso de baja o pérdida de dispositivo.

8. Diagnóstico: primero las variables, después el protocolo

Ante un error de autenticación, sigue este orden; suele ser más rápido que recrear la clave una y otra vez:

  1. Confirma que la variable llegó al proceso: imprime solo si existe, nunca su valor. En un notebook reinicia el kernel; en un contenedor comprueba que se inyectó en el servicio correcto.
  2. Revisa sobrescrituras explícitas: busca un api_key vacío o un base_url incorrecto en el código o la configuración.
  3. Comprueba la ruta del protocolo: los endpoints compatibles con OpenAI suelen terminar en /v1; una sección de más o de menos provoca un 404.
  4. Verifica el ID del modelo: el nombre visible no es el identificador de la API; compáralo carácter por carácter con la página de precios.
  5. Separa por código de estado: 401 apunta a la clave; 403, a permisos y alcance de modelos; 429, a concurrencia y cuota; ante 5xx, reintenta y conserva la hora de la solicitud.
  6. Revisa red y proxy: las variables de proxy y los certificados corporativos también pueden hacer fallar la solicitud con un mensaje que parece de autenticación.

Cambia una sola variable a la vez. Probar primero otra clave y después otro modelo permite distinguir rápidamente entre «esta clave no sirve» y «este modelo no está disponible».

Preguntas frecuentes

¿LangChain necesita una API key por sí mismo?

El framework no la necesita. Solo hacen falta credenciales cuando llamas a modelos remotos, servicios de embeddings o el servicio de observabilidad LangSmith.

Configuré la variable de entorno y aun así recibo 401. ¿Por qué?

Hay cuatro causas habituales: la variable solo existe en la terminal actual, el kernel del notebook no se reinició, el código pasa una clave vacía de forma explícita o la clave tiene espacios o saltos de línea al principio o al final. Confirma primero que la variable existe dentro del proceso y después si el código la sobrescribe.

¿Una sola clave puede llamar a varios modelos?

Depende del servicio al que pertenezca. Una pasarela unificada suele permitir que una clave llame a los modelos de su lista; con conexión directa, cada fabricante tiene su clave. Aunque se admitan varios modelos, puede haber una lista permitida; manda la configuración de la consola.

¿La clave aparece en las trazas de LangSmith?

Las trazas guardan principalmente entradas, salidas y cadenas de llamadas; que incluyan cabeceras depende de la integración y de la configuración de enmascaramiento. No trates la plataforma de trazas como una caja fuerte de claves: los callbacks personalizados, los logs de excepciones y los proxies de depuración filtran cabeceras con más facilidad. Revisa el enmascaramiento antes de activarlos.

¿Hay que cambiar código después de rotar la clave?

Si el código lee la clave desde variables de entorno o un gestor de secretos, normalmente no hace falta: basta actualizar el valor y reiniciar o volver a desplegar. Si la clave está codificada en el código, un notebook o una imagen, primero hay que pasar a inyección externa y después rotar.

Siguiente paso

La gestión de claves en LangChain se resume en cuatro frases: la clave pertenece al proveedor del modelo, no al framework; en local usa .env y en producción un gestor de secretos; separa claves por entorno y uso; al rotar, crea primero la nueva y revoca después la antigua. Si necesitas una entrada única para varios modelos y gestión de uso y cuota por clave, puedes registrarte en ZSQH AI Gateway; los modelos y precios se rigen por la página de precios de modelos.

Lecturas relacionadas: