Voltar ao catálogo
LiteLLM: The Universal LLM Gateway (v1.82 - 2026 Edition)
Uma série de podcasts abrangente sobre o LiteLLM, desde o Python SDK e o tratamento unificado de exceções até ao Proxy Server, load balancing, virtual keys, observability e funcionalidades empresariais como RBAC e MCP Gateway.
A Reproduzir
Click play to start
0:00
0:00
1
A Pedra de Roseta dos LLMs: O Python SDK
Descubra a identidade central do LiteLLM: uma interface Python unificada para mais de 100 LLMs. Saiba como integrar o LiteLLM na sua base de código existente para chamar o Anthropic, Vertex ou Ollama sem alterar a sua lógica de parsing compatível com a OpenAI.
2
A Magia da Tradução de Parâmetros
Deixe de se preocupar com qual fornecedor suporta qual hiperparâmetro. Descubra como o SDK do LiteLLM traduz automaticamente os inputs padrão da OpenAI, como temperature, tools e max_tokens, em todos os modelos upstream.
3
Tratamento Unificado de Exceções
Escreva os seus blocos try-except apenas uma vez. Descubra como o LiteLLM captura erros personalizados da AWS, Google e Azure, mapeando-os perfeitamente para as exceções padrão da OpenAI, como RateLimitError.
4
O Gateway de LLMs: Configurar o Proxy Server
Tire o LiteLLM do seu código local e leve-o para uma plataforma centralizada. Saiba como iniciar o Proxy Server do LiteLLM via Docker e configurar os seus primeiros endpoints usando o ficheiro config.yaml.
5
Gestão Centralizada de Segredos
Mantenha as suas chaves de API fora de configurações em texto simples. Saiba como ligar o LiteLLM a gestores de segredos empresariais, como o AWS Secrets Manager ou o Azure Key Vault, para obter credenciais de forma dinâmica.
6
Model Aliases: A Atualização Oculta
Migre utilizadores para novos modelos de forma silenciosa. Descubra como usar Model Aliases no LiteLLM para mapear pedidos de um modelo para um endpoint completamente diferente sem alterar qualquer código do lado do cliente.
7
Load Balancing para Alto Rendimento
Evite rate limits e tempo de inatividade encaminhando o tráfego de forma inteligente. Explore por que razão o simple-shuffle é a estratégia recomendada para load balancing em produção através de múltiplos deployments.
8
Falhas de API e Fallbacks
Nunca mais sofra com tempo de inatividade de IA. Saiba como configurar fallbacks de modelos no LiteLLM para que, se o seu fornecedor principal falhar, o tráfego seja automaticamente reencaminhado para um fornecedor de backup.
9
Fallbacks de Context Window
Pare de pagar a mais por context windows enormes em prompts curtos. Saiba como usar verificações pre-call e context window fallbacks para encaminhar documentos sobredimensionados para modelos especializados.
10
Controlar Pedidos Pendentes com Timeouts
Não deixe que APIs lentas congelem a sua aplicação. Descubra como configurar timeouts globais e stream timeouts no LiteLLM para abortar pedidos parados e acionar fallbacks rápidos.
11
Virtual Keys para FinOps
Bloqueie o uso da sua API com precisão. Saiba como gerar virtual keys usando o LiteLLM, definindo limites rigorosos de RPM, TPM e orçamento para proteger a sua organização de custos de IA descontrolados.
12
Monitorização de Gastos e Custom Tags
Atribua cada cêntimo de gastos com LLMs com precisão. Saiba como passar tags de metadados nos seus pedidos e gerar relatórios de gastos abrangentes usando o LiteLLM.
13
Caching para Velocidade e Poupança
Pare de pagar pelas mesmas respostas de LLMs repetidamente. Saiba como configurar exact caching com Redis e semantic caching com Qdrant para reduzir drasticamente a latência e os custos de API.
14
RBAC: Capacitar os Team Admins
Distribua a gestão da plataforma com segurança. Entenda o Role-Based Access Control do LiteLLM, delegando poder aos Org Admins e Team Admins sem comprometer a segurança global.
15
Guardrails de Segurança
Adicione uma camada de segurança invisível aos seus pedidos de LLMs. Saiba como configurar guardrails pre-call e post-call no LiteLLM para bloquear prompt injections e mascarar PII antes que chegue a fornecedores externos.
16
Gestão Dinâmica de Callbacks
Dê aos microsserviços o poder da privacidade. Saiba como usar o header x-litellm-disable-callbacks para permitir que pedidos de API sensíveis optem por não participar no registo central de observability.
17
Observability Integrada
Obtenha visibilidade instantânea do seu tráfego de LLMs. Saiba como canalizar telemetria, traces e exceções para ferramentas como o Langfuse e o Sentry usando callbacks simples de sucesso e falha.
18
Métricas do Prometheus e Saúde dos Pods
Sinta o pulso do seu proxy. Descubra como expor o endpoint /metrics ao Prometheus, rastrear pedidos in-flight e usar custom tags para segmentar dados no Grafana.
19
Text-to-Speech Universal
Padronize a sua geração de voz. Descubra como chamar modelos Text-to-Speech do Gemini, Vertex e AWS Polly usando exatamente o mesmo formato de endpoint de áudio compatível com a OpenAI.
20
A Ponte para a Assistants API
Faça a gestão do estado da conversa sem esforço entre fornecedores. Saiba como o LiteLLM encapsula modelos não nativos na interface padrão da Assistants API da OpenAI, permitindo-lhe usar Threads e Messages em todo o lado.
21
O MCP Gateway
Potencie os seus modelos com ferramentas de forma centralizada. Descubra como configurar servidores Model Context Protocol (MCP) via HTTP, SSE ou STDIO no LiteLLM, dando a qualquer LLM acesso a capacidades externas.
22
A2A: Rastrear Agentes Autónomos
Coloque os agentes autónomos sob controlo. Saiba como invocar agentes complexos do LangGraph ou Bedrock através do proxy usando o protocolo A2A, permitindo o agrupamento de traces e a monitorização unificada de gastos.
23
Rotações de Chaves com Zero-Downtime
Alcance transições de segurança com zero-downtime. Saiba como configurar rotações de chaves automáticas programadas e grace periods para virtual keys de nível empresarial no LiteLLM.
24
A Admin UI e o AI Hub
Torne a sua plataforma de IA acessível a todos. Saiba como gerir a Admin UI, ajustar credenciais da UI e usar o AI Hub para permitir que os developers descubram de forma segura os modelos e agentes permitidos.
Episódios
1
A Pedra de Roseta dos LLMs: O Python SDK
3m 56sDescubra a identidade central do LiteLLM: uma interface Python unificada para mais de 100 LLMs. Saiba como integrar o LiteLLM na sua base de código existente para chamar o Anthropic, Vertex ou Ollama sem alterar a sua lógica de parsing compatível com a OpenAI.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal para LLMs, episódio 1 de 24. Trocas a tua API key da OpenAI por uma da Anthropic e, de repente, toda a tua aplicação crasha. Cada provider formata os seus inputs e outputs de maneira diferente, obrigando-te a escrever e manter parsing logic customizada para cada novo modelo. A Pedra de Roseta dos LLMs, o Python SDK do LiteLLM, resolve isto completamente.
Existe o mito comum de que o LiteLLM compete com o LangChain. Não compete. O LiteLLM não é uma agent framework. Não orquestra tools, não gere memória, nem faz chain de tarefas. É simplesmente um drop-in replacement para o client da OpenAI.
O Python SDK do LiteLLM traduz mais de cem APIs de providers diferentes para o formato exato de chat completion da OpenAI. Não precisas de aprender as nuances específicas das APIs da Vertex AI, Anthropic ou Hugging Face. Escreves o teu código uma vez usando o standard da OpenAI, e o LiteLLM trata da translation layer em background.
O núcleo deste SDK é uma única interface unificada chamada completion function. Quando usas esta função, forneces uma model string. Esta string diz ao LiteLLM qual provider contactar. Também passas parâmetros standard da OpenAI, como temperature, max tokens e a messages list. O LiteLLM pega nesses parâmetros standard e mapeia-os para os campos corretos do provider de destino.
Considera um cenário em que queres chamar o Claude 3.5 Sonnet. Usando o SDK standard da Anthropic, precisarias de estruturar os teus prompt blocks de acordo com os requisitos específicos da sua message API. Com o LiteLLM, basta chamares a completion function. Passas o model name para o Claude. Passas o teu messages array standard, usando dicionários com roles de user e system. Finalmente, forneces a tua API key da Anthropic, seja como parâmetro ou como environment variable.
Aqui está o ponto chave. O response object devolvido por esta função está estruturado exatamente como um chat completion object da OpenAI.
Quando queres extrair o texto gerado pelo Claude, percorres exatamente o mesmo caminho que percorrerias para um modelo GPT. Olhas para o choices array. Pegas no primeiro item. Acedes ao message object. Lês a content property. A lógica da tua aplicação não faz ideia de que foi a Anthropic a gerar o texto. A network request subjacente foi traduzida, enviada para o provider, e a resposta foi mapeada de volta para o schema da OpenAI antes mesmo de chegar às tuas variáveis.
Esta abstração aplica-se a toda a interação. Abrange erros, estatísticas de token usage, e até mesmo streaming responses. Se a Anthropic devolver um rate limit error, o LiteLLM mapeia-o para a rate limit exception standard da OpenAI. O teu código de error handling existente apanha-o sem modificações. Se pedires uma streaming response, o LiteLLM faz yield de chunks que são exatamente iguais aos streaming chunks da OpenAI.
Podes iterar por diferentes modelos simplesmente alterando o string value do model parameter e trocando a environment variable da API key. O resto do teu código Python permanece completamente estático. Já não estás preso a um único ecossistema só porque escreveste o teu integration code para um provider específico.
O verdadeiro valor da unified completion interface é desacoplar a lógica da tua aplicação das infinitas variações nas APIs dos model providers, transformando mudanças complexas de infraestrutura em simples string swaps.
Obrigado por ouvirem, happy coding a todos!
2
A Magia da Tradução de Parâmetros
3m 42sDeixe de se preocupar com qual fornecedor suporta qual hiperparâmetro. Descubra como o SDK do LiteLLM traduz automaticamente os inputs padrão da OpenAI, como temperature, tools e max_tokens, em todos os modelos upstream.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal para LLMs, episódio 2 de 24. Será que o Claude espera max tokens, max tokens to sample, ou algo completamente diferente? Sempre que mudas de provider de modelos, geralmente tens de reescrever todo o payload da tua request à API para corresponder às convenções de nomenclatura específicas deles. O Parameter Translation Magic é a feature que faz este problema desaparecer.
Quando chamas a função de completion no LiteLLM, só tens de escrever a tua request usando o formato de parameters standard da OpenAI. Não precisas de procurar as dictionary keys específicas para a Anthropic, Vertex AI ou Cohere. A library interceta os teus inputs formatados para a OpenAI e traduz tudo automaticamente para a estrutura exata que o provider de destino exige.
Vamos olhar para um cenário específico. Queres fazer uma query a um modelo Gemini da Vertex AI. Precisas que ele use function calling, e queres que as respostas sejam altamente determinísticas, por isso defines a temperature para zero ponto dois. Se estivesses a escrever uma integração direta, a Vertex tem a sua própria forma única e profundamente nested de definir tools e configurar a geração do modelo. Com o LiteLLM, ignoras isso completamente. Constróis o teu array de tools usando a sintaxe JSON standard da OpenAI. Passas esse array, juntamente com o teu valor de temperature, diretamente para a chamada de completion. O LiteLLM agarra nesses arguments da OpenAI, desmonta-os e constrói o payload correto da API da Vertex AI antes de enviar a network request.
Este mapping automático é incrivelmente eficiente, mas introduz um edge case. O que acontece se passares um parameter da OpenAI que o modelo de destino simplesmente não suporta de todo? Talvez especifiques uma presence penalty, mas o provider não tem um conceito correspondente. Por default, o LiteLLM é strict. Vai lançar uma exception e falhar a chamada de completion. Esta é uma escolha de design deliberada. Impede que percas silenciosamente configurações que podem ser críticas para o comportamento da tua aplicação.
Falhar de forma strict é seguro, mas pode ser frustrante se estiveres a fazer routing dinâmico de prompts de utilizadores por dezenas de modelos diferentes em produção. Se quiseres que a chamada tenha sucesso independentemente de pequenos mismatches de parameters, adicionas uma flag chamada drop params definida como true dentro da tua chamada de completion. Quando ativas isto, o LiteLLM continua a traduzir tudo o que consegue fazer map com sucesso. Mas, se encontrar um parameter da OpenAI que o provider de destino não reconhece, simplesmente remove esse parameter não suportado do payload e envia o resto da request. A chamada tem sucesso, e o parameter não suportado é ignorado com segurança.
Se preferires lidar com as capabilities de forma graciosa no teu próprio código, em vez de dependeres de drops silenciosos, existe uma tool de introspeção built-in. Podes chamar uma helper function chamada get supported openai params. Passas o nome do modelo como argument, e ela devolve uma lista de todos os parameters standard da OpenAI que fazem map com sucesso para esse modelo específico. Isto permite-te verificar o que um modelo realmente suporta em runtime antes de executares a chamada de completion.
Aqui está o insight principal. O verdadeiro valor da parameter translation é que promove a specification da API da OpenAI de um schema específico do vendor para uma linguagem de interface universal para toda a tua application stack.
Obrigado por ouvirem, happy coding a todos!
3
Tratamento Unificado de Exceções
4m 05sEscreva os seus blocos try-except apenas uma vez. Descubra como o LiteLLM captura erros personalizados da AWS, Google e Azure, mapeando-os perfeitamente para as exceções padrão da OpenAI, como RateLimitError.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal para LLMs, episódio 3 de 24. Escrever lógica de error handling customizada para quinze APIs de IA diferentes é uma ótima maneira de desperdiçares o teu fim de semana. Cada API tem a sua própria maneira de te avisar que estás a enviar demasiadas requests ou que o teu token é inválido. Para evitar que escrevas condicionais infinitas, o LiteLLM usa Unified Exception Handling.
Em vez de aprenderes como a Anthropic, a Cohere ou a Google expõem os seus erros, só precisas de lidar com um standard. O LiteLLM mapeia todas as exceptions subjacentes do provider diretamente para os tipos de exception standard da OpenAI. Se uma request falhar, o gateway interceta o erro raw, traduz com base no status code HTTP e na resposta do provider, e lança o erro correspondente da OpenAI.
Considera um cenário em que usas um endpoint de inferência do Hugging Face. Durante as horas de ponta, o endpoint fica sobrecarregado com tráfego. O Hugging Face vai rejeitar a request. Se estivesses a chamar a API deles diretamente, precisarias de fazer parse do erro HTTP cinco zero três service unavailable específico deles, ou de uma mensagem de throttling customizada. Com o exception mapping unificado, não precisas de um exception handler específico do Hugging Face.
Estruturas o teu código usando um bloco try standard à volta da tua chamada de geração. Logo abaixo, adicionas um bloco except desenhado para apanhar um Rate Limit Error da OpenAI. Dentro desse bloco, acionas a tua função de exponential backoff standard. A tua aplicação faz pausa, espera e faz retry da request. Se mais tarde trocares o Hugging Face pelo Vertex AI, a tua lógica de backoff permanece exatamente a mesma. O Rate Limit Error da OpenAI apanha o evento de throttling do Vertex com a mesma fiabilidade.
Este mapping cobre todo o conjunto standard de falhas. Podes apanhar um API Timeout Error da OpenAI quando um servidor remoto encrava. Podes apanhar um Authentication Error quando uma API key sofre rotação ou expira. Podes lidar com um API Connection Error em caso de quebras de rede, ou um Bad Request Error se o teu payload estiver malformado. O código da tua aplicação trata todo o ecossistema de IA como se estivesse a comunicar exclusivamente com um único provider previsível.
Aqui está o insight principal. Às vezes, uma abstração limpa esconde demasiado contexto. Um Bad Request Error genérico da OpenAI diz-te que a chamada falhou, mas muitas vezes precisas de saber exatamente o porquê. O Azure, por exemplo, aplica filtros de content policy rigorosos. Se o Azure rejeitar um prompt porque viola as safety guidelines, mapear isso para um erro genérico da OpenAI corre o risco de perder a safety flag específica de que precisas para fazer log ou mostrar ao utilizador.
Para resolver isto, o LiteLLM anexa um atributo chamado provider specific fields ao objeto da exception. Quando apanhas uma exception da OpenAI no teu código, podes inspecionar este atributo. Ele contém um dicionário com os dados de erro originais e não mapeados, diretamente do provider. Ficas com o fluxo unificado de try e except para routing e retries, mas manténs os dados granulares para debugging e auditoria.
Constróis os teus sistemas resilientes, os teus retries e os teus circuit breakers inteiramente à volta das classes de exception da OpenAI. Standardizar as tuas error boundaries impede que failure modes específicos do provider interfiram na core logic da tua aplicação.
Obrigado por ouvirem, happy coding a todos!
4
O Gateway de LLMs: Configurar o Proxy Server
4m 17sTire o LiteLLM do seu código local e leve-o para uma plataforma centralizada. Saiba como iniciar o Proxy Server do LiteLLM via Docker e configurar os seus primeiros endpoints usando o ficheiro config.yaml.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal de LLM, episódio 4 de 24. E se toda a tua empresa pudesse partilhar um único endpoint de LLM sem nunca expor as raw API keys do provider? Passar de uma integração local de SDK para uma arquitetura centralizada muda a forma como geres o acesso. Este é O Gateway de LLM: Configurar o Proxy Server.
Muitos developers assumem que introduzir um proxy middleware custom obriga a escrever custom client code para comunicar com ele. Isso é falso. O proxy LiteLLM fala o formato nativo da API da OpenAI. Qualquer library, aplicação ou script que saiba comunicar com a OpenAI só precisa de ter o seu base URL atualizado para apontar para o teu novo proxy.
Para iniciar o proxy server, precisas de um ficheiro de configuração. Este é um ficheiro YAML que define a tua lógica de routing. O núcleo deste ficheiro é uma secção chamada model list. Esta lista mapeia os nomes dos modelos que as tuas aplicações internas vão pedir para os modelos reais do backend provider.
Dentro da model list, cada entrada requer duas partes principais. A primeira é o model name. Este é o alias que expões aos teus utilizadores. Podes chamar-lhe internal-chat-model. A segunda é um bloco chamado LiteLLM parameters. É aqui que configuras o destino real. Esta distinção é importante. O model name é o que o teu client pede, mas o bloco LiteLLM parameters define o que realmente processa a request.
Se estiveres a fazer routing para um deployment do Azure OpenAI, o teu bloco LiteLLM parameters vai conter a model string específica do Azure, o base URL da tua API do Azure e a API version. Também dizes ao LiteLLM qual é a environment variable que guarda a API key. Não fazes hardcode da key no próprio ficheiro YAML.
Com o ficheiro de configuração pronto, fazes o deploy do proxy usando Docker. Usas a imagem oficial do LiteLLM do GitHub Container Registry. Quando corres o container Docker, executas três passos específicos. Mapeias a tua porta local quatro mil para a porta quatro mil do container. Montas o teu ficheiro de configuração YAML no container para que o proxy possa ler a tua model list. Finalmente, passas as tuas credenciais reais do provider para o container como environment variables.
Assim que o container estiver a correr, o proxy está live e à escuta no localhost, porta quatro mil. Testas exatamente como testarias a API oficial da OpenAI. Fazes um HTTP POST request standard usando uma tool como o cURL. Apontas para o localhost porta quatro mil, seguido pelo path slash chat slash completions. No request body, especificas o alias que definiste antes como o model, e forneces o teu messages array.
O proxy recebe este standard payload. Ele lê o alias pedido, procura-o no teu ficheiro de configuração e extrai os Azure parameters. A seguir, assina a request com a tua API key do Azure, encaminha-a para a Microsoft e traduz a response de volta para o formato exato que o teu client espera.
Aqui está o ponto chave. O proxy abstrai completamente o backend provider da application layer. Se decidires trocar o teu deployment do Azure por um provider completamente diferente no próximo mês, não tocas numa única linha do teu application code. Apenas atualizas os LiteLLM parameters no teu ficheiro de configuração YAML e reinicias o container.
O valor principal do proxy server é que as tuas client applications nunca sabem, e nunca precisam de saber, qual é o cloud provider que está realmente a gerar os tokens.
Obrigado por ouvirem, happy coding a todos!
5
Gestão Centralizada de Segredos
3m 40sMantenha as suas chaves de API fora de configurações em texto simples. Saiba como ligar o LiteLLM a gestores de segredos empresariais, como o AWS Secrets Manager ou o Azure Key Vault, para obter credenciais de forma dinâmica.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal de LLMs, episódio 5 de 24. Se a master API key da tua empresa estiver num ficheiro YAML em plaintext num servidor de produção, a tua equipa de segurança vai ter um mau dia. Credenciais hardcoded são um incidente prestes a acontecer. A solução é a Gestão Centralizada de Secrets.
Quando corres um gateway, ele precisa de aceder às API keys do teu upstream provider para fazer o routing do tráfego com sucesso. A abordagem default é muitas vezes colocar estas credenciais numa environment variable local ou diretamente no ficheiro de configuração principal. A Gestão Centralizada de Secrets muda este pattern por completo. Permite que o gateway leia dinamicamente as credenciais de um vault enterprise externo, como o AWS Secrets Manager, o Azure Key Vault, o Google Secret Manager ou o HashiCorp Vault.
Para ativares esta ligação, configuras dois campos específicos dentro do bloco de settings gerais do teu ficheiro de configuração. O primeiro campo é o key management system. Aqui, defines o identificador do teu provider de vault. Se estiveres a usar a AWS, defines isto como aws_kms. O segundo campo são as key management settings. Esta é uma estrutura aninhada onde forneces os parâmetros de ligação exatos que o teu vault específico exige, como a região da AWS de destino ou outros detalhes de autenticação necessários.
Assim que a ligação ao vault estiver estabelecida, tens de dizer às configurações de routing de cada modelo para irem buscar as suas keys a esse vault. Fazes isto usando um prefixo de string específico em vez da key real.
Aqui está o ponto crucial. Em vez de escreveres a string da key real, escreves a expressão o s ponto environ barra, seguida imediatamente pelo nome exato do teu secret, tal como existe no vault.
Vamos analisar um cenário concreto. Queres fazer o routing do tráfego para um modelo do Azure, e a API key real está guardada com segurança no AWS Secrets Manager com o nome azure api key production. No teu ficheiro de configuração, configuras o bloco de routing do modelo. Mas para o campo api key, defines o valor como o s ponto environ barra azure api key production.
Quando o gateway processa um request para esse modelo, ele vê o prefixo. Sabe que não deve usar essa string como uma key literal. Em vez disso, faz uma chamada segura ao AWS Secrets Manager, pede o valor para aquele nome de secret exato e obtém a key real para autenticar o request. A key em plaintext nunca toca no teu disco. O teu ficheiro de configuração permanece totalmente limpo e seguro para fazeres commit para o version control.
Isto cobre a obtenção de credenciais upstream para o gateway. Mas a integração com o secret manager funciona nos dois sentidos. Também pode escrever dados. Quando usas o gateway para gerar novas virtual proxy keys para as tuas equipas internas de engenharia, podes configurar o sistema para guardar automaticamente essas keys recém-geradas diretamente no teu secret manager. Isto garante que as credenciais internas que emites são guardadas e geridas com os mesmos controlos de segurança que as credenciais de provider que consomes.
Os teus ficheiros de configuração definem a estrutura da tua infraestrutura de routing, mas nunca devem conter os seus secrets. O lugar mais seguro para guardar uma API key na configuração do teu gateway é em lado nenhum.
Obrigado por ouvirem, happy coding a todos!
6
Model Aliases: A Atualização Oculta
4m 02sMigre utilizadores para novos modelos de forma silenciosa. Descubra como usar Model Aliases no LiteLLM para mapear pedidos de um modelo para um endpoint completamente diferente sem alterar qualquer código do lado do cliente.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Universal LLM Gateway, episódio 6 de 24. E se pudesses migrar toda a tua base de utilizadores da OpenAI para a Anthropic sem lhes pedir para atualizarem uma única linha do seu código de integração? Ou mudar silenciosamente um utilizador do free-tier para uma alternativa open-source sem quebrar a lógica existente da sua aplicação? O mecanismo que torna esta transição silenciosa possível chama-se Model Aliases.
É fácil confundir aliases com routing, por isso vamos separar os dois. O routing trata do load balancing entre vários deployments exatamente do mesmo modelo. Se tiveres três instâncias separadas da Azure OpenAI a correr a mesma versão do GPT quatro, o routing distribui o tráfego de entrada uniformemente entre elas para evitar rate limits. Os aliases fazem algo completamente diferente. Um alias interceta o nome de um modelo pedido e mapeia-o para um modelo totalmente diferente por trás do proxy.
Aplicas este mapeamento no momento em que crias uma virtual key para um cliente. Quando envias a tua request para o key generation endpoint do LiteLLM, incluis um objeto de aliases no teu payload. Este objeto é simplesmente um dicionário que faz a correspondência entre o nome do modelo que o cliente vai pedir e o nome do modelo que tu realmente pretendes servir.
Vejamos um cenário concreto. Tens um segmento de utilizadores do free-tier. Eles construíram originalmente as suas tools à volta do GPT quatro, e essa string exata está atualmente hardcoded nas suas network requests. Servir o GPT quatro a utilizadores não pagantes é caro, por isso decides redirecionar os seus prompts para um endpoint interno e altamente otimizado do Mistral sete B.
Para conseguires isto, geras uma nova virtual key especificamente para este grupo de utilizadores. No payload de geração, defines um alias que mapeia a string GPT quatro diretamente para o nome do teu deployment do Mistral sete B. Dás esta nova virtual key aos utilizadores. Eles não modificam o código da sua aplicação. Eles continuam a enviar requests de chat completion standard para o teu proxy, pedindo explicitamente o GPT quatro.
Aqui está o ponto chave. O proxy LiteLLM recebe a request de entrada e autentica a virtual key. Lê a configuração associada a essa chave específica e deteta a tua regra de alias. Antes de fazer o routing do payload para um provider externo, o proxy reescreve o parâmetro do modelo em memória. Remove o GPT quatro e substitui-o pelo Mistral sete B. A request segue para o teu deployment interno do Mistral, gera o texto e faz o routing da resposta de volta através do proxy para o cliente.
A aplicação cliente recebe o formato de resposta standard que espera. Os seus parsers funcionam perfeitamente, e a aplicação continua a funcionar normalmente. Os developers que mantêm essa aplicação cliente não fazem a mínima ideia de que o modelo de linguagem subjacente foi trocado.
Como os aliases estão associados diretamente a virtual keys individuais, em vez da configuração global do servidor, tu manténs controlo absoluto sobre diferentes segmentos de utilizadores. Uma chave pode fazer o alias do tráfego para um modelo mais barato para utilizadores gratuitos, enquanto outra chave permite que o tráfego premium passe sem modificações. Também podes usar exatamente esta mesma lógica para lidar com deprecations de modelos. Quando um provider retira um modelo antigo, tu simplesmente fazes um alias do nome antigo para a nova versão, poupando todos os teus clientes de terem de fazer push de atualizações de código de emergência. O aspeto mais poderoso de um model gateway não é apenas gerir o tráfego de rede, mas sim fazer o decoupling das expectativas do cliente da realidade física da tua arquitetura de backend.
Obrigado por ouvirem, happy coding a todos!
7
Load Balancing para Alto Rendimento
3m 31sEvite rate limits e tempo de inatividade encaminhando o tráfego de forma inteligente. Explore por que razão o simple-shuffle é a estratégia recomendada para load balancing em produção através de múltiplos deployments.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal de LLM, episódio 7 de 24. Finalmente conseguiste acesso de produção ao Azure OpenAI, lançaste a tua app, e imediatamente bateste num erro massivo de rate limit no teu primeiro grande pico de tráfego. Tens a quota, mas está a fazer bottleneck numa única região. O Load Balancing para High Throughput resolve isto. Para lidar com grandes volumes de requests sem atingir os limites, precisas de distribuir o teu tráfego por vários deployments idênticos. No LiteLLM, fazes isto configurando um router. Agrupas vários endpoints de backend debaixo de um único model name lógico. Imagina que tens uma app suportada por cinco deployments do Azure espalhados por cinco regiões geográficas diferentes. Quando a tua app pede uma completion, o router decide qual dessas cinco regiões recebe a request. Controlas esta lógica de decisão definindo uma routing strategy nas settings do teu router. A abordagem intuitiva é o usage-based routing, onde o sistema envia a request para o deployment que tiver o menor tráfego no momento. Mas fazer isso requer o tracking exato do uso de tokens em tempo real. Fazer o tracking do state em tempo real significa fazer uma network call para uma cache como o Redis por cada request, antes mesmo de o prompt ser enviado. Isso adiciona uma latency tax permanente à tua app. Para ambientes de produção de high throughput, queres evitar esse hop extra. A abordagem recomendada é uma estratégia chamada simple-shuffle. O simple-shuffle não faz tracking do state em tempo real. Seleciona aleatoriamente um endpoint da tua pool com base em pesos predefinidos. Quando adicionas os teus cinco deployments do Azure ao teu ficheiro de configuração, atribuis um limite a cada um, geralmente Requests Per Minute, ou RPM. Também podes usar Tokens Per Minute, ou TPM. Se a tua região primária tiver um limite de RPM de dez mil, e uma região secundária tiver um limite de RPM de cinco mil, o simple-shuffle lê esses números e trata-os como pesos. Vai fazer o routing automaticamente do dobro do tráfego para a região primária. Nos bastidores, o router pega na lista de deployments disponíveis para esse modelo, tem em conta os seus pesos de RPM, e faz um shuffle para uma lista aleatória para essa request específica. Tenta o primeiro deployment da lista. Como a randomização respeita rigorosamente os limites de RPM que configuraste, o teu tráfego distribui-se perfeitamente pelas cinco regiões ao longo do tempo, contornando os rate limits sem o overhead da monitorização em tempo real. Para configurar isto, abres o teu ficheiro de configuração e defines o parâmetro de routing strategy para simple-shuffle. Depois, na tua model list, defines os teus cinco endpoints do Azure. Dás a todos eles exatamente o mesmo model name. Por fim, anexas o parâmetro RPM a cada definição de endpoint com o teu peso desejado. Quando a tua app chama o router usando esse model name, o router trata da matemática e da randomização automaticamente. Ganhas os benefícios de uma arquitetura distribuída sem precisares de uma dependência do Redis. A melhor maneira de lidar com massive scale é muitas vezes trocar o tracking perfeito em tempo real por uma randomização stateless e estatisticamente previsível. Obrigado por ouvirem, happy coding a todos!
8
Falhas de API e Fallbacks
3m 34sNunca mais sofra com tempo de inatividade de IA. Saiba como configurar fallbacks de modelos no LiteLLM para que, se o seu fornecedor principal falhar, o tráfego seja automaticamente reencaminhado para um fornecedor de backup.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal de LLM, episódio 8 de 24. Quando o teu provider principal de modelos de linguagem sofre um outage, a tua aplicação vai abaixo com ele, ou muda silenciosamente para um backup? Hoje vamos falar sobre outages de API e fallbacks, o mecanismo exato que mantém o teu sistema online quando endpoints externos falham.
Primeiro, ajuda distinguir isto de um conceito relacionado. Fallbacks não são load balancing. O load balancing distribui proativamente o teu tráfego por vários deployments ativos para evitar sobrecarregar um único endpoint. Os fallbacks, por outro lado, são resgates estritamente reativos. Ficam inativos durante o funcionamento normal e só entram em ação depois de ocorrer uma falha definitiva.
O objetivo principal é manter um uptime elevado, idealmente atingindo a marca dos 99,9%, mesmo quando os teus providers upstream não o conseguem. APIs externas vão inevitavelmente lançar erros 500 de internal server error ou exceções 429 de rate limit. Quando isto acontece, uma configuração de fallback diz ao proxy para intercetar o erro em trânsito e encaminhar o request para um provider alternativo, protegendo completamente o código da tua aplicação da interrupção.
Configuras isto no teu ficheiro YAML de configuração do proxy usando um array de fallbacks. Considera um cenário concreto. O teu deployment principal é o gpt-4. Queres garantir que, se o gpt-4 ficar offline, o proxy tenta automaticamente o claude-3-opus em alternativa.
No teu ficheiro de configuração, defines o setup do teu modelo gpt-4 como é habitual. Dentro dessa definição de modelo específica, adicionas uma key fallbacks. O valor desta key é simplesmente um array de strings, onde cada string é o nome de outro modelo definido na tua configuração. Adicionas o claude-3-opus a este array.
Quando a tua aplicação envia um prompt ao proxy a pedir o gpt-4, o LiteLLM encaminha-o para o endpoint principal. Se esse endpoint devolver um erro, a lógica do proxy apanha-o. Se tiveres retries configurados, pode tentar o endpoint principal mais algumas vezes. Mas assim que o primário falha definitivamente, o proxy aciona a sequência de fallback.
É aqui que a coisa fica interessante. O proxy pega no prompt e nos parâmetros originais exatos. Como o LiteLLM normaliza o formato da API, traduz de forma transparente o request com o formato da OpenAI para o formato da Anthropic exigido pelo Claude. Envia imediatamente o request traduzido para o endpoint de backup. O código da tua aplicação não precisa de lidar com nenhuma lógica de erro, reescrever o prompt, ou gerir API keys para o segundo provider. O proxy lida com todo o pivot internamente.
Não estás limitado a um único backup. O array de fallbacks aceita uma lista de modelos. Se o teu gpt-4 primário falhar, e depois o teu primeiro fallback claude-3-opus também falhar, o proxy avança para o próximo nome no array. Percorre a lista sequencialmente. Se chegar ao fim do array e todos os modelos de backup falharem, só então é que o proxy devolve um erro à tua aplicação cliente.
Aqui está o ponto chave. Ao colocares em camadas diversos modelos de fallback na tua configuração, isolas efetivamente o código da tua aplicação da instabilidade externa, transformando outages graves dos providers em nada mais do que picos de latência invisíveis para os teus utilizadores finais.
Obrigado por ouvirem, happy coding a todos!
9
Fallbacks de Context Window
3m 31sPare de pagar a mais por context windows enormes em prompts curtos. Saiba como usar verificações pre-call e context window fallbacks para encaminhar documentos sobredimensionados para modelos especializados.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Universal LLM Gateway, episódio 9 de 24. Usar um modelo de context de 128k caro para cada query de um utilizador é um enorme desperdício de dinheiro. Mas se, por default, optares por um modelo mais pequeno e mais barato, um utilizador que faça upload de um PDF enorme vai quebrar a tua aplicação imediatamente. O mecanismo que resolve esta tensão chama-se Context Window Fallbacks.
Podes assumir que o fallback routing só acontece depois de uma API do provider devolver um código de erro. Isso é verdade para fallbacks gerais de fiabilidade, mas os limites de context funcionam de maneira diferente. O LiteLLM consegue lidar com os tamanhos do prompt de forma proativa usando uma configuração chamada enable pre-call checks. Quando mudas este boolean para true na configuração do teu router, o proxy interrompe a request e calcula a contagem exata de tokens do prompt antes sequer de o provider o ver.
Aqui está o ponto-chave. Tu configuras um modelo primário, como um modelo altamente económico, e nesse mesmo bloco de configuração, defines uma lista de context window fallbacks a apontar para um modelo muito maior. Quando chega uma nova request, o pre-call check é executado. Se a contagem de tokens calculada couber no limite do modelo primário, a request prossegue normalmente. Se o prompt for demasiado grande, o LiteLLM descarta a route primária por completo. Encaminha instantaneamente a request para o modelo de fallback maior.
Isto significa que nunca recebes um erro de context length da API upstream. Também significa que evitas a penalização de latência de esperar que um provider rejeite o payload inicial. A aplicação que faz a request não faz ideia de que o routing mudou nos bastidores.
O LiteLLM depende do seu model registry interno para saber os limites exatos de context para diferentes providers. No entanto, podes querer impor limites mais rigorosos. Talvez queiras acionar o fallback mais cedo para deixar mais espaço para os output tokens gerados, ou talvez estejas a fazer routing para um custom deploy com uma alocação de memória fora do standard. Lidas com isto fazendo override do parâmetro max input tokens diretamente na configuração do teu modelo. Especificar este valor força o proxy a usar o teu limite custom ao avaliar o pre-call check.
Pensa no tráfego standard de uma aplicação. Um utilizador faz uma pergunta simples em texto. O proxy conta cinquenta tokens, valida que cabe no limite, e faz o routing para o GPT-3.5. Uns minutos depois, esse mesmo utilizador faz upload de um PDF enorme com oitenta mil tokens. O proxy calcula o novo tamanho, vê que excede o limite do GPT-3.5, e redireciona-a automaticamente e estritamente para o GPT-4-128k. A lógica da tua aplicação permanece completamente estática. Só pagas pelo modelo premium quando o payload realmente o exige.
Mover a validação de tokens do código da tua aplicação para a proxy layer transforma a tua estratégia de fallback de uma rede de segurança passiva num motor ativo de otimização de custos.
Obrigado por ouvirem, happy coding a todos!
10
Controlar Pedidos Pendentes com Timeouts
3m 59sNão deixe que APIs lentas congelem a sua aplicação. Descubra como configurar timeouts globais e stream timeouts no LiteLLM para abortar pedidos parados e acionar fallbacks rápidos.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Universal LLM Gateway, episódio 10 de 24. Não há nada pior para a experiência do utilizador do que um chatbot que mostra um loading spinner durante quarenta e cinco segundos simplesmente porque uma API upstream encravou silenciosamente. Precisas de uma forma fiável de cortar dead connections instantaneamente para que o teu sistema consiga recuperar. Resolvemos isto domando hanging requests com timeouts.
Quando fazes routing de tráfego para language models externos, atrasos na rede e outages do provider são inevitáveis. Se um provider deixar de responder, o comportamento default de muitos clientes HTTP é manter a ligação aberta durante muito tempo. O LiteLLM interceta este problema usando dois mecanismos de timeout distintos. O primeiro é o parâmetro standard de timeout. Esta setting dita o tempo total máximo que o LiteLLM vai esperar para que uma request inteira seja concluída, desde o momento em que é enviada até ao último caráter gerado.
Se definires um timeout standard de trinta segundos, e o model demorar trinta e um segundos a escrever uma resposta longa, o LiteLLM vai abortar a request. Isto funciona bem para background tasks ou gerações curtas, sem streaming. No entanto, aplicar um timeout total a uma aplicação de streaming cria um problema estrutural. Uma resposta exaustiva pode legitimamente demorar sessenta segundos a fazer stream de volta para o utilizador. Se definires um timeout total curto para apanhar stalled requests, vais matar acidentalmente gerações perfeitamente saudáveis e long-running.
É aqui que a coisa fica interessante. O LiteLLM fornece um segundo parâmetro chamado stream timeout. Esta setting mede especificamente o tempo até ao primeiro token. Controla exatamente quanto tempo o gateway vai esperar para receber o chunk inicial de dados do provider. Assim que esse primeiro pedaço de dados chega, o relógio do stream timeout para, e a ligação permanece aberta para o resto da geração.
Considera um cenário concreto. Estás a fazer routing de tráfego para um endpoint primário do Azure OpenAI. Dentro do teu ficheiro de configuração, defines o teu model block e adicionas o parâmetro de stream timeout, definindo-o para dois segundos. Um utilizador submete um prompt complexo. O LiteLLM reencaminha esta request para o Azure. Normalmente, o servidor upstream processa o prompt e devolve o primeiro chunk numa fração de segundo. Mas, neste caso, o node específico do Azure encrava.
O gateway começa a contar. Passa um segundo. Passam dois segundos. O primeiro chunk não chega. Como definiste um stream timeout de dois segundos, o LiteLLM recusa-se a esperar que o timeout HTTP standard dispare. Ele aborta a ligação à força exatamente na marca dos dois segundos.
Abortar a dead request é apenas metade do benefício arquitetónico. Ao forçar uma falha rápida, o LiteLLM ativa imediatamente a tua lógica de fallback. No momento em que a request do Azure faz timeout, o gateway faz reroute do exato mesmo prompt do utilizador para o próximo node disponível e saudável na tua lista de deploy. O utilizador sente um atraso quase impercetível de dois segundos antes de o texto começar a fazer stream, evitando por completo uma interface congelada.
Tens a flexibilidade de impor estas regras a diferentes níveis. Podes aplicar um timeout global a todas as routed requests, ou podes fazer fine-tune por model. Um model pesado de raciocínio lógico pode exigir um stream timeout mais tolerante de cinco ou dez segundos, enquanto um model de classificação rápida deve fazer failover após apenas um segundo.
A capacidade de resposta da tua aplicação é governada não apenas pela rapidez com que o teu provider principal tem sucesso, mas pela agressividade com que forças uma stalled connection a falhar. Obrigado por ouvirem, happy coding a todos!
11
Virtual Keys para FinOps
4m 00sBloqueie o uso da sua API com precisão. Saiba como gerar virtual keys usando o LiteLLM, definindo limites rigorosos de RPM, TPM e orçamento para proteger a sua organização de custos de IA descontrolados.
Olá, daqui é o Alex do DEV STORIES DOT EU. LiteLLM: O Gateway Universal para LLM, episódio 11 de 24. Um script descontrolado escrito por um developer júnior pode facilmente gerar uma conta de dez mil dólares na OpenAI da noite para o dia. A plataforma do provider subjacente continua a aceitar requests tão rápido quanto o loop os consegue disparar. As Virtual Keys para FinOps são a forma de parares isto antes que aconteça.
Existe uma confusão comum entre master keys e virtual keys. Nunca deves dar a tua master key a um developer. A master key é a tua credencial administrativa. O seu principal objetivo é autenticar a tua plataforma para criar virtual keys. As virtual keys são as credenciais restritas que tu realmente entregas aos developers ou aplicações para usarem no seu código.
Tu crias uma nova credencial fazendo um request HTTP POST para o endpoint de key generate no teu proxy LiteLLM. Autorizas este request usando a tua master key como bearer token. O body deste request é onde defines as salvaguardas financeiras.
Considera um cenário em que estás a provisionar acesso para um estagiário de verão. Queres garantir que ele tem acesso suficiente para construir um protótipo, mas precisas de uma garantia absoluta de que não vai derreter o teu orçamento de infraestrutura. Passas dois parâmetros específicos no teu payload JSON para forçar isto.
Primeiro, defines o limite financeiro ao configurar o parâmetro max budget. Se definires este valor para dez, alocas exatamente dez dólares americanos a esta key específica. Este é um limite vitalício rígido. Assim que o custo total de todos os prompts e completions associados a esta key atingir dez dólares, a key é automaticamente desativada e vai rejeitar todos os requests seguintes.
Segundo, controlas a velocidade desses requests ao configurar o parâmetro RPM limit. RPM significa requests por minuto. Se definires o limite de RPM para um, o proxy impõe estritamente um request por cada janela de sessenta segundos. Se um loop infinito acidental no código do estagiário tentar disparar cem requests instantaneamente, o proxy processa o primeiro e rejeita imediatamente os restantes noventa e nove com um erro standard de rate limit.
Quando envias este payload para o endpoint generate, o LiteLLM processa as regras e devolve uma response que contém a nova virtual key gerada. Esta key parece idêntica a uma credencial standard de um provider, começando tipicamente com um prefixo sk. Entregas esta string ao estagiário.
Aqui está o ponto chave. O developer usa esta virtual key exatamente como usaria uma key da OpenAI ou da Anthropic, apontando a sua client library standard para o URL do teu proxy LiteLLM em vez da internet pública. Quando um request chega, o proxy interceta-o. Ele consulta a sua base de dados interna para verificar se a virtual key existe. Depois, verifica se a key excedeu o seu budget de dez dólares ou o seu limite de velocidade de um request por minuto.
Se o request passar em ambas as verificações, o proxy troca a virtual key pela tua API key corporativa real e reencaminha o payload para o provider. Quando o provider responde, o proxy calcula o custo exato dos tokens de prompt e completion com base nos preços publicados desse modelo específico. Ele deduz essa fração de cêntimo do budget de dez dólares da virtual key, regista a transação e envia a response de volta para o developer. O developer não tem qualquer conhecimento da troca de credenciais subjacente ou da contabilidade interna.
Ao impor limites na camada de proxy, as virtual keys intercetam requests não autorizados ou descontrolados antes mesmo de chegarem ao billing provider, garantindo matematicamente que um script comprometido ou mal escrito nunca consiga exceder o seu budget atribuído.
Obrigado por ouvirem, happy coding a todos!
12
Monitorização de Gastos e Custom Tags
3m 42sAtribua cada cêntimo de gastos com LLMs com precisão. Saiba como passar tags de metadados nos seus pedidos e gerar relatórios de gastos abrangentes usando o LiteLLM.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: The Universal LLM Gateway, episódio 12 de 24. O teu diretor financeiro acabou de entrar e perguntou exatamente qual é a nova feature do produto que está a consumir o orçamento mensal de AI. Abres o dashboard do teu provider, mas tudo o que vês é uma única fatura agregada enorme para toda a empresa. Não tens resposta. O Spend Tracking e as Custom Tags no LiteLLM resolvem este ponto cego.
Quando fazes o routing de requests através do LiteLLM, o proxy calcula automaticamente o custo de cada completion com base no modelo específico e no token count. Um valor total em dólares é inútil se não o conseguires atribuir a uma source específica. A forma mais simples de agrupar este gasto é usando o parâmetro user standard na tua chamada de chat completion. Passas uma string única que representa o teu cliente final. O LiteLLM interceta isto, calcula o custo e faz o log para esse user ID específico.
Fazer o tracking por user resolve um problema, mas, muitas vezes, um único user faz trigger de múltiplos processos de backend. Imagina que tens um workload de classificação de documentos, e o departamento de faturação precisa de um report a agrupar o gasto por background jobs específicos. Um user ID não ajuda aqui. É aqui que entram as custom tags. O LiteLLM permite-te anexar um array de strings a qualquer request, e vai fazer o tracking do gasto associado a essas strings exatas.
Aqui está o insight principal. Libraries standard como o SDK oficial da OpenAI ou o LangChain não conhecem nativamente a metadata do LiteLLM. Se tentares passar um parâmetro não reconhecido chamado metadata, o SDK vai removê-lo ou fazer throw de um erro antes sequer de o request chegar ao proxy. Para contornar isto, usas um parâmetro chamado extra body. Esta é uma escape hatch standard integrada nos SDKs modernos, especificamente para injetar custom fields.
Vamos ver como fazer isto com um request do LangChain. Configuras o teu objeto de chat model standard. Quando chamas o método invoke, passas o teu prompt como é habitual. Juntamente com o prompt, passas um parâmetro chamado extra body. Defines isto como um dictionary. Dentro desse dictionary, crias uma key chamada metadata. Dentro de metadata, adicionas uma key chamada tags, a apontar para um array de strings. Podes passar uma string como job ID quatro zero dois. O LangChain empacota este extra body exatamente como está e envia-o pela rede. O LiteLLM recebe o payload, extrai as tuas tags do bloco de metadata, e associa o custo preciso dessa chamada de LLM ao job ID quatro zero dois.
Isto cobre os inputs. E quanto aos outputs? Assim que o teu tráfego estiver a fluir com estas tags, precisas de extrair os dados. Fazes isto ao consultar o endpoint do global spend report no teu proxy LiteLLM. Fazes um request HTTP GET standard para este endpoint. O proxy devolve um payload JSON a detalhar exatamente para onde o dinheiro foi. Ele agrupa o teu gasto total por API key, por user e, crucialmente, por cada custom tag que forneceste. Podes entregar isto diretamente ao teu departamento de faturação. Eles podem ver instantaneamente que o job de classificação de documentos custou exatamente quatro dólares e vinte cêntimos, independentemente de qual modelo subjacente tenha gerido o routing.
Fazer o tagging do teu tráfego ao nível do proxy significa que a granularidade da tua faturação já não é ditada pela forma como o teu cloud provider estrutura as suas faturas; é inteiramente definida pelo contexto da tua própria aplicação.
Obrigado por ouvirem, happy coding a todos!
13
Caching para Velocidade e Poupança
3m 51sPare de pagar pelas mesmas respostas de LLMs repetidamente. Saiba como configurar exact caching com Redis e semantic caching com Qdrant para reduzir drasticamente a latência e os custos de API.
Daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal de LLMs, episódio 13 de 24. Porquê pagar a uma API externa para gerar exatamente a mesma explicação básica mil vezes? Gastas créditos e obrigas os utilizadores a esperar por cálculos que já foram feitos. Resolver esta ineficiência é a essência do Caching para Velocidade e Poupança.
O LiteLLM gere o caching inteiramente ao nível do proxy. Quando um request chega, o proxy verifica se já viu exatamente este prompt antes. Se sim, devolve a resposta armazenada imediatamente. A latência cai de segundos para milissegundos, e o custo da API desce para zero. Para configurar isto, usas o teu ficheiro config ponto yaml. Ativas o caching no teu bloco de global settings definindo cache como true, e especificas o teu cache type. O Redis é o backend standard para caching de exact match. Forneces o host, a port e a password do Redis, e o proxy encarrega-se de armazenar os pares de input-output.
Mas o exact caching é frágil. Procura por um string match perfeito. Se um utilizador pedir, escreve um poema sobre o LiteLLM, e outro utilizador pedir, cria um poema LiteLLM, um exact cache vê dois requests completamente diferentes. Encaminha o segundo request para o modelo de linguagem pesado, desperdiçando tempo e dinheiro numa tarefa redundante só porque o fraseamento mudou ligeiramente.
É aqui que entra o semantic caching. Em vez de comparar strings de raw text, o semantic caching compara o significado subjacente dos prompts. O LiteLLM suporta o Qdrant, uma base de dados vetorial, para lidar com isto. Quando configuras o semantic caching, tens de especificar um embedding model juntamente com o teu modelo de geração principal. Quando um request chega, o proxy passa primeiro o prompt para o embedding model. Este modelo converte o texto num vetor, que é uma representação matemática do significado do prompt.
O proxy consulta então o Qdrant para ver se já existe um vetor semelhante na cache. Como escreve um poema e cria um poema partilham a mesma intenção semântica, os seus vetores mapeiam-se muito próximos no espaço. O Qdrant deteta esta similaridade. Se o match for suficientemente próximo, o proxy puxa a resposta em cache do primeiro utilizador e entrega-a ao segundo utilizador. Saltas completamente o passo pesado de geração de texto, pagando apenas uma fração de cêntimo pelo rápido embedding lookup.
Configurar isto requer mais algumas linhas no teu config ponto yaml. Mudas o cache type para qdrant semantic. Defines parâmetros específicos do Qdrant, como o URL do endpoint do Qdrant e a tua API key. Mais importante ainda, defines um similarity threshold. Este é um valor decimal entre zero e um. Um threshold alto, como ponto nove nove, exige um fraseamento quase idêntico. Um threshold mais baixo, como ponto oito, apanha variações mais amplas, mas aumenta o risco de devolver uma resposta desatualizada ou ligeiramente off-topic se dois prompts soarem semelhantes, mas tiverem intenções diferentes.
Aqui está o insight principal. O semantic caching não é apenas um mecanismo de armazenamento, é um filtro ativo para a intenção do utilizador. Afinar o teu similarity threshold é a única coisa que separa uma redução massiva de custos de devolveres respostas irrelevantes aos teus utilizadores.
Obrigado por ouvirem, happy coding a todos!
14
RBAC: Capacitar os Team Admins
3m 36sDistribua a gestão da plataforma com segurança. Entenda o Role-Based Access Control do LiteLLM, delegando poder aos Org Admins e Team Admins sem comprometer a segurança global.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal de LLMs, episódio 14 de 24. És um platform engineer, e passas metade do teu dia a responder a mensagens a pedir novas API keys ou aumentos de budget. Cada onboarding de developers transforma-se num ticket de IT que bloqueia o trabalho deles e desperdiça o teu tempo. A solução é delegar o controlo sem perder a supervisão, usando Role-Based Access Control.
O LiteLLM suporta quatro user roles específicas para gerir esta delegação. São elas o proxy admin, o org admin, o team admin e o internal user. O proxy admin está no topo. Se fazes o deploy do LiteLLM, tu és o proxy admin. Configuras os modelos, preparas a base de dados e estabeleces as regras globais. Mas não deves gerir os pedidos de API keys do dia a dia. É aí que entra a hierarquia.
Podes agrupar a tua empresa em organizações, que representam grandes departamentos, e equipas, que são grupos de trabalho específicos dentro desses departamentos. O org admin pode gerir equipas dentro da sua organização específica. Mas o verdadeiro poder operacional reside no team admin.
Aqui está o ponto chave. Podes delegar todas as tarefas administrativas locais a um líder de departamento, tornando-o num team admin. Como proxy admin, configuras a estrutura inicial uma única vez. Crias uma equipa, aplicas um limite de budget rígido de quinhentos dólares por mês, e designas o lead developer como team admin. Depois disso, retiras-te completamente do processo.
O team admin tem agora autonomia para gerir os seus próprios engenheiros. Pode fazer login na UI ou usar a API para adicionar novos utilizadores à sua equipa. Pode gerar novas API keys para esses developers e monitorizar o gasto agregado do seu grupo específico. Crucialmente, qualquer API key criada pelo team admin ou pelos seus engenheiros fica automaticamente vinculada a esse budget de equipa de quinhentos dólares. O team admin tem controlo local total, mas não pode gastar um único cêntimo além do limite imposto pelo proxy admin.
Abaixo do team admin está o internal user. Esta é a role atribuída aos developers normais que escrevem o código. Um internal user tem acesso restrito. Pode ver o seu próprio gasto de tokens e, se o team admin permitir, gerar as suas próprias API keys pessoais. A sua visão do sistema é estritamente limitada a si próprio. Não pode ver o budget geral da equipa, não pode ver as API keys pertencentes aos seus colegas, e certamente não pode modificar as definições da equipa.
Para configurar isto de forma programática, o proxy admin faz um único pedido de API para o endpoint de criação de equipa. Passas o nome da equipa, o parâmetro de max budget, e um array de user IDs com a tag da role de team admin. O sistema devolve um team ID. A partir daí, o líder do departamento usa esse team ID para encaminhar os seus próprios pedidos de gestão, fazendo bypass total à equipa de platform engineering.
O Role-Based Access Control no LiteLLM não serve apenas para esconder botões numa user interface; trata-se de restringir fisicamente o gasto de tokens ao nível do grupo, enquanto se delega a gestão de API keys para as pessoas que realmente lideram os projetos.
Obrigado por ouvirem, e happy coding a todos!
15
Guardrails de Segurança
3m 34sAdicione uma camada de segurança invisível aos seus pedidos de LLMs. Saiba como configurar guardrails pre-call e post-call no LiteLLM para bloquear prompt injections e mascarar PII antes que chegue a fornecedores externos.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: The Universal LLM Gateway, episódio 15 de 24. Confiar que um modelo de linguagem se porte bem não é uma estratégia de segurança. Se um utilizador colar acidentalmente dados sensíveis de clientes num prompt, pedir ao modelo para os ignorar educadamente já vem tarde. Precisas de um segurança à porta, e é exatamente isso que as Security Guardrails oferecem.
As Security Guardrails no LiteLLM atuam como uma camada de segurança invisível entre os clientes da tua aplicação e os providers do modelo de linguagem. Elas intercetam o tráfego da API em duas fases distintas. A primeira fase chama-se pre call. Esta é executada depois de o LiteLLM receber a request da tua aplicação, mas mesmo antes de reencaminhar esse payload para o provider externo. A segunda fase chama-se post call, que é acionada depois de o modelo gerar a sua resposta, mas antes de o LiteLLM enviar essa resposta de volta ao cliente original.
Defines toda esta lógica de routing diretamente no teu ficheiro config dot yaml. No bloco de settings do proxy, defines as tuas guardrails especificando um endpoint ou uma integração suportada, e depois atribuis-lhe um mode de pre call ou post call.
Vejamos um cenário concreto usando uma guardrail de pre call. Imagina que um funcionário pede a um modelo alojado na cloud para resumir um ticket de suporte, mas esse ticket contém números de Segurança Social dos EUA. Tu não queres, de todo, que esses números saiam da tua rede interna. Podes configurar o Microsoft Presidio como a tua guardrail de pre call. Quando a aplicação envia o prompt, o LiteLLM interceta a request e passa o texto ao Presidio. O Presidio faz o scan do texto, localiza o número de Segurança Social e substitui-o por uma máscara genérica. O LiteLLM depois pega neste prompt sanitizado e envia-o pela internet para o cloud provider. O modelo externo gera um resumo com base no texto mascarado, e o código da tua aplicação funciona como se nada de anormal tivesse acontecido.
Aqui está o ponto chave. Não tens de aplicar estas regras globalmente a todo o teu tráfego. O LiteLLM permite-te associar guardrails ao nível do modelo específico. Isto é crucial quando operas uma arquitetura híbrida. Podes configurar o teu routing para que qualquer prompt enviado a um modelo de public cloud passe pela rigorosa guardrail de mascaramento de PII. No entanto, se fizeres o routing desse exato mesmo prompt para um modelo open source a correr no teu próprio hardware on premises, simplesmente deixas a guardrail de fora do bloco de configuração desse modelo. O modelo local processa os dados raw, sem máscara, porque a informação nunca cruza a fronteira da tua rede. Evitas overhead de processamento desnecessário e preservas o contexto exato.
O mode de post call opera usando exatamente o mesmo flow, mas na viagem de regresso. Quando o modelo externo responde, o LiteLLM passa o output pelas tuas guardrails de post call. Isto permite-te avaliar o texto em busca de linguagem tóxica, URLs internos alucinados, ou menções não autorizadas a concorrentes, antes sequer de o utilizador o ver. Se a guardrail de post call sinalizar o conteúdo, o LiteLLM interceta a viagem de regresso. Bloqueia o texto e devolve um erro de segurança ao cliente, em vez de entregar o output prejudicial.
Ao lidar com isto diretamente ao nível do proxy, a arquitetura da tua aplicação permanece totalmente inalterada. Os teus developers simplesmente enviam completion requests standard, e o proxy aplica as tuas regras de compliance. As camadas de segurança mais fiáveis são aquelas com as quais o código da tua aplicação nunca tem de se preocupar. Obrigado por ouvirem, happy coding a todos!
16
Gestão Dinâmica de Callbacks
3m 51sDê aos microsserviços o poder da privacidade. Saiba como usar o header x-litellm-disable-callbacks para permitir que pedidos de API sensíveis optem por não participar no registo central de observability.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal de LLM, episódio 16 de 24.
Queres fazer log de todo o tráfego LLM para debugging, mas o que acontece quando um microserviço envia dados de compliance altamente sensíveis que não podem ser guardados de forma alguma? Podes assumir que tens de desativar a observabilidade globalmente, deixando todo o teu sistema cego apenas para proteger algumas API routes específicas. A Gestão Dinâmica de Callbacks resolve esta tensão, permitindo-te controlar o logging por request.
Numa configuração standard do LiteLLM, os callbacks tratam de enviar os teus payloads de request e response para plataformas de observabilidade externas. Configuras plataformas como o Langfuse ou o Datadog ao nível do proxy e, por default, elas capturam tudo o que passa por lá. O equívoco comum é achar que este logging é um sistema de tudo ou nada. As pessoas pensam muitas vezes que, para lidar com dados sensíveis, têm de fazer deploy de um proxy completamente separado com o logging desativado. A Gestão Dinâmica de Callbacks elimina esse trabalho extra.
Considera um microserviço que lida com registos médicos. A aplicação precisa de processar os sintomas dos pacientes através de um modelo de linguagem, mas enviar esses dados sensíveis para uma logging stack de terceiros viola o compliance. Para evitar este leak, o microserviço simplesmente adiciona um HTTP header específico ao seu request de saída. Este header chama-se x-litellm-disable-callbacks. Defines o seu valor como uma lista separada por vírgulas das plataformas específicas que queres ignorar.
Para o serviço de registos médicos, o microserviço passa o header com o valor langfuse vírgula datadog. Quando o proxy LiteLLM recebe este request, avalia o header antes de acionar o modelo de linguagem. O prompt é enviado para o provider, e a response é encaminhada de volta para o cliente como habitualmente. A intervenção acontece durante a fase de telemetria. O proxy lê o header disable e bloqueia ativamente o payload de ser reencaminhado para os endpoints de observabilidade especificados para essa única transação. Entretanto, todas as outras aplicações a aceder ao mesmo proxy em simultâneo continuam a fazer log do seu tráfego sem qualquer interrupção.
É aqui que a coisa fica interessante. Dar aos clientes o poder de desativar os seus próprios audit logs introduz um potencial risco de segurança. Em ambientes altamente regulados, os developers não devem ter sempre a autoridade para ocultar o seu tráfego. Se a tua infraestrutura exige um audit trail rigoroso e inalterável para cada prompt, tens de o impor centralmente.
Tratas disto usando compliance locking. Dentro do ficheiro de configuração do proxy, no bloco de definições gerais, defines um parâmetro chamado allow dynamic callback disabling para false. Esta única configuração estabelece uma política global rigorosa que se sobrepõe a quaisquer instruções client-side.
Se um microserviço tentar passar o header disable callbacks enquanto este lock estiver ativo, o proxy não ignora o header silenciosamente. Em vez disso, rejeita a transação por completo e devolve um erro HTTP 403 Forbidden. Este mecanismo garante que o tráfego ou cumpre a política global obrigatória de logging, ou é dropped antes de chegar ao modelo de linguagem.
A verdadeira utilidade da Gestão Dinâmica de Callbacks é que transfere a privacidade de dados de um deployment rígido de infraestrutura para um parâmetro ágil ao nível do request, dando na mesma aos platform engineers a palavra final sobre o compliance.
Obrigado por ouvirem, happy coding a todos!
17
Observability Integrada
3m 31sObtenha visibilidade instantânea do seu tráfego de LLMs. Saiba como canalizar telemetria, traces e exceções para ferramentas como o Langfuse e o Sentry usando callbacks simples de sucesso e falha.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal para LLMs, episódio 17 de 24. Quando um utilizador se queixa de que a IA lhe deu uma resposta bizarra há três dias, como é que vais buscar o prompt exato que a causou? Analisar logs da aplicação à procura de payloads JSON de várias linhas é um pesadelo. Precisas de dados de trace estruturados, mas criar integrações customizadas para cada ferramenta de monitorização consome horas de engenharia. Este problema exato é resolvido por Drop-in Observability.
Em vez de escreveres wrapper functions customizadas para medir o tempo das tuas API calls, contar tokens e apanhar timeouts, o LiteLLM interceta o tráfego nativamente. Ele expõe dois hooks principais nas tuas settings: o success callback e o failure callback. Estes callbacks atuam como mecanismos de routing automático para a tua telemetria. Eles aceitam um array de strings que representam providers externos de observabilidade suportados. Tu simplesmente indicas o nome da ferramenta que queres usar, e o LiteLLM traduz os seus dados de request internos para o formato exato que essa ferramenta específica espera.
Vejamos o success callback. Ele é acionado no momento em que um modelo de linguagem devolve uma resposta válida. Quando isto acontece, o LiteLLM captura automaticamente um snapshot da transação. Isto inclui o input prompt exato enviado para o modelo, o output gerado, o tempo que demorou a gerar e o uso preciso de tokens. Para enviar estes dados para uma ferramenta externa, abres as tuas settings do LiteLLM e defines a variável do success callback para uma lista que contém a string "langfuse". Desde que as tuas chaves de autenticação do Langfuse estejam presentes nas tuas variáveis de ambiente, o sistema trata do resto. Aqui está o ponto chave. O processo de logging acontece de forma assíncrona em background. A thread principal da tua aplicação nunca bloqueia enquanto espera que o provider de observabilidade reconheça o trace. Os teus utilizadores sentem zero latência adicionada.
Isto trata do happy path. Para os erros, usas o failure callback. Ele é acionado quando uma API call dá timeout, atinge um rate limit do provider, ou falha completamente. Sem um tracing adequado, um erro de LLM surge muitas vezes como um status code opaco. Ao definires a tua variável de failure callback para uma lista que contém a string "sentry", mapeias as exceções de LLM diretamente para o teu workflow de error tracking existente. Quando um request falha, o LiteLLM empacota o tipo de exceção, o nome do modelo e o input tentado, e depois envia esse contexto diretamente para o Sentry.
Para configurares isto no teu código, não precisas de modificar as tuas API calls reais. Só tocas na configuração global. Atribuis as tuas ferramentas escolhidas aos arrays de callback uma única vez durante o startup da aplicação. A partir desse ponto, cada completion call que faças é monitorizada. A tua lógica principal permanece totalmente desacoplada da tua infraestrutura de logging. Se decidires trocar o Langfuse por outro provider no próximo mês, mudas uma string num array.
O verdadeiro poder dos drop-in callbacks não é apenas evitar boilerplate code. É padronizar a forma da tua telemetria em dezenas de providers de LLMs diferentes, para que a tua plataforma de monitorização veja exatamente um formato consistente, independentemente de qual modelo subjacente respondeu ao prompt.
Obrigado por ouvirem, happy coding a todos!
18
Métricas do Prometheus e Saúde dos Pods
3m 27sSinta o pulso do seu proxy. Descubra como expor o endpoint /metrics ao Prometheus, rastrear pedidos in-flight e usar custom tags para segmentar dados no Grafana.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Universal LLM Gateway, episódio 18 de 24. Se um request LLM demora dez segundos, o provider de IA está lento, ou o event loop do teu proxy está completamente entupido? Não consegues corrigir um bottleneck até saberes exatamente onde ele está. As Prometheus Metrics e a Pod Health no LiteLLM dão-te essa visibilidade exata.
O LiteLLM expõe um endpoint de métricas standard no path barra metrics. Um erro comum ao monitorizar gateways de IA é tratar todos os atrasos de resposta como latência do provider LLM. Isso é impreciso. Existem dois períodos de espera distintos. Primeiro, há a latência da queue pré-ASGI. Este é o tempo que um request passa à espera dentro da tua infraestrutura antes mesmo de o proxy começar a processá-lo. Segundo, há a latência do LLM propriamente dita, que é o tempo gasto à espera que a OpenAI, a Anthropic ou outro provider devolva os tokens. O endpoint de métricas separa estes números para saberes exatamente a quem culpar por uma resposta lenta.
Para monitorizar a saúde do teu pod, dependes de um gauge específico chamado litellm in flight requests. Esta métrica rastreia o número exato de requests concorrentes a ser processados ativamente por um pod a qualquer milissegundo. Esta é uma medida em tempo real da queue depth. Quando há um pico de tráfego, este número sobe.
Considera um cenário concreto. O teu dashboard de monitorização mostra um pico enorme na duração total dos requests. Os utilizadores queixam-se de respostas lentas. Se olhares apenas para o tempo total, podes assumir que a OpenAI está com um outage. Mas quando verificas o endpoint de métricas, a latência do provider está estável nos dois segundos. Aqui está o insight principal. Olhas para os litellm in flight requests e vês que dispararam de vinte para duzentos. Isto prova que o atraso não é da OpenAI. A queue do teu pod está completamente sobrecarregada. Armado com este gauge exato, podes configurar a tua infraestrutura para disparar um evento de auto-scale no momento em que os in-flight requests cruzam um threshold específico, a arrancar novos proxy pods antes que o event loop sufoque.
Também precisas de saber quem está a gerar este tráfego. O LiteLLM suporta custom prometheus tags. Quando um request chega ao gateway, podes passar custom metadata no payload do request, como um project ID, um departamento, ou o nome de uma aplicação. O LiteLLM extrai estas custom tags e anexa-as como labels às métricas do Prometheus. Em vez de apenas veres que o gateway processou dez mil tokens, vês que a aplicação de marketing processou sete mil tokens e o analytics dashboard processou três mil. Isto dá a DevOps a capacidade de agrupar o uso de tokens, a queue depth e a latência por tenants específicos.
O takeaway mais crítico para a performance do gateway é este. Nunca faças auto-scale do teu proxy de IA com base na latência total de resposta, porque vais desperdiçar dinheiro a fazer scale up quando o provider externo estiver simplesmente lento; faz scale com base no teu gauge de in-flight requests para reagires apenas quando a queue da tua própria infraestrutura estiver realmente cheia.
Obrigado por ouvirem, happy coding a todos!
19
Text-to-Speech Universal
3m 46sPadronize a sua geração de voz. Descubra como chamar modelos Text-to-Speech do Gemini, Vertex e AWS Polly usando exatamente o mesmo formato de endpoint de áudio compatível com a OpenAI.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal de LLMs, episódio 19 de 24. Queres adicionar geração de voz à tua app, mas escrever código de integração custom para o formato de áudio de cada provider exige manutenção constante. Cada vez que trocas de um modelo de voz da OpenAI para um modelo de voz da Google, os campos JSON necessários, os API paths e os return types de áudio mudam completamente. O mecanismo que resolve isto é o Text-to-Speech Universal usando a audio-speech bridge do LiteLLM.
Em vez de manteres API clients separados para a OpenAI, Vertex AI e Gemini, padronizas a tua aplicação num único formato. O LiteLLM expõe um endpoint unificado que imita exatamente a route standard de audio-speech da OpenAI. Constróis uma request com o teu texto, o nome do modelo escolhido e uma preferência de voz, e envias para o LiteLLM como se estivesses a falar diretamente com a OpenAI. O gateway depois traduz este payload standard para o formato específico exigido pelo teu provider de destino.
Aqui está o ponto chave. Muitos providers de IA não oferecem uma API de Text-to-Speech dedicada e direta que faça stream de ficheiros de áudio out of the box. Dependendo do provider, aceder a um modelo de voz nativamente muitas vezes exige fazer o routing da request através de um endpoint genérico de text completion. Podes ter de passar flags de configuração muito específicas, enviar um system prompt complexo e, depois, extrair strings de áudio com encoding base64 profundamente aninhadas numa JSON response. O LiteLLM abstrai toda esta camada de tradução. Ele trata da negociação da API, faz o unpack da estrutura de resposta proprietária e isola os dados de áudio em si.
Considera um cenário concreto. Decides gerar áudio falado usando o modelo em preview Gemini Flash TTS da Google. No código da tua aplicação, apontas o teu HTTP client standard para o URL do teu proxy LiteLLM no path audio-speech. Defines o parâmetro model para apontar para o modelo Gemini Flash TTS. Atribuis o teu plain text ao parâmetro input, e especificas um identificador de voz válido.
Quando executas a request, o LiteLLM interceta o payload. Autentica-se de forma segura na Google Cloud ou Vertex AI, dependendo do teu setup. Faz o repackage do teu plain text e seleção de voz para o JSON schema específico que a API da Google exige. Quando o modelo da Google processa o texto e devolve o resultado, o LiteLLM interceta a resposta proprietária. Em vez de forçar a tua aplicação cliente a fazer o parse de um payload custom da Google Cloud, o LiteLLM extrai os raw audio bytes. Faz a bridge de forma transparente na transport layer, fazendo imediatamente o stream de um ficheiro MP3 standard de volta para o teu cliente. A tua aplicação de frontend ou backend recebe uma audio stream standard, completamente alheia ao facto de que a geração subjacente foi realizada pela Google em vez da OpenAI.
Esta lógica de bridge significa que escreves a integração do teu cliente de Text-to-Speech apenas uma vez. Se um novo modelo de áudio mais rápido for lançado pela Vertex amanhã, só precisas de alterar a model string na tua request. O código da aplicação que lida com a stream de MP3 permanece totalmente intacto. Tratar a geração de áudio exatamente da mesma forma que tratas a geração de texto permite padronizar a lógica da tua aplicação. Ao forçar todas as requests de Text-to-Speech através de uma única interface unificada, podes fazer o route, load-balance e configurar failovers para a tua geração de áudio em providers completamente diferentes, sem escrever uma única linha de código de fallback específico do provider. Obrigado por ouvirem, happy coding a todos!
20
A Ponte para a Assistants API
3m 49sFaça a gestão do estado da conversa sem esforço entre fornecedores. Saiba como o LiteLLM encapsula modelos não nativos na interface padrão da Assistants API da OpenAI, permitindo-lhe usar Threads e Messages em todo o lado.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal para LLMs, episódio 20 de 24. A OpenAI lida com o state da conversa de forma excelente, mantendo o código do teu client totalmente stateless. Mas prender a tua arquitetura a um único provider apenas para manter essa gestão de state é um preço alto a pagar. A Assistants API Bridge no LiteLLM resolve este problema.
A bridge é uma feature do proxy LiteLLM que expõe os endpoints exatos da Assistants API da OpenAI. Tu acedes a paths standard como os endpoints v one assistants e v one threads, mas fazes o routing da geração de texto para qualquer modelo que queiras.
As interfaces standard de chat completion são stateless. Sempre que fazes uma pergunta, o teu client tem de enviar todo o histórico da conversa de volta para o server. Isto consome bandwidth e complica o teu código client-side. A Assistants API resolve isto mantendo o histórico da conversa no server dentro de um objeto Thread. Tu simplesmente fazes append de novas mensagens à thread e dizes ao server para fazer run do assistant. O problema é que a maioria dos outros providers, desde setups locais até alternativas cloud enterprise, não oferece esta interface stateful de forma nativa.
A bridge do LiteLLM faz o polyfill desta funcionalidade em falta. Para que funcione, tu configuras o proxy LiteLLM para se ligar a uma base de dados. Esta base de dados vai atuar como a storage layer para o state da tua conversa. A seguir, apontas o teu client OpenAI existente para o URL do proxy LiteLLM em vez dos servers default da OpenAI.
O flow lógico começa com a criação de um assistant. Envias um request ao proxy a definir as instruções do assistant e a especificar um target model. Isto pode ser um deploy do Azure OpenAI ou um modelo Astra compatível com a OpenAI. O proxy guarda esta configuração na sua base de dados.
A seguir, crias uma thread. Uma thread é simplesmente um container vazio guardado pelo proxy. Quando um utilizador diz algo, envias um request para adicionar uma mensagem a essa thread específica. O proxy guarda a mensagem. Até este ponto, o large language model subjacente não foi sequer contactado.
Aqui está o insight principal. A bridge só fala com o teu target model quando fazes trigger de um run. Quando dizes ao proxy para fazer run do assistant numa thread específica, o LiteLLM vai buscar todo o histórico de mensagens à sua base de dados. Ele formata esse histórico num payload standard e stateless de chat completion. Depois, envia esse flat payload para o modelo subjacente que configuraste anteriormente.
O modelo avalia a conversa e devolve uma resposta ao proxy. O LiteLLM pega nesse texto, empacota-o como uma nova mensagem do assistant, guarda-o na base de dados da thread e atualiza o status do run para completed. O teu client faz poll ao proxy, vê o status completed e faz fetch da mensagem mais recente exatamente como faria normalmente.
O código da tua aplicação permanece completamente inalterado. Ele continua a achar que está a falar com um sistema stateful nativo. O proxy lida com a tradução de forma transparente, pegando num request stateful do client, executando uma call stateless ao modelo e mantendo a persistence layer pelo meio.
Esta separation of concerns significa que a arquitetura do teu client pode depender de uma interface de API moderna e state-managed, enquanto a tua infraestrutura permanece totalmente livre para trocar os modelos subjacentes com base em requisitos de custo, privacidade ou performance.
Obrigado por ouvirem, happy coding a todos!
21
O MCP Gateway
4m 05sPotencie os seus modelos com ferramentas de forma centralizada. Descubra como configurar servidores Model Context Protocol (MCP) via HTTP, SSE ou STDIO no LiteLLM, dando a qualquer LLM acesso a capacidades externas.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway Universal para LLMs, episódio 21 de 24. Tens um modelo Llama open-source a correr localmente, mas queres que ele dispare ações ou leia ficheiros usando exatamente as mesmas integrações do GitHub que o teu agente Claude Code utiliza. Não queres reescrever a lógica da tua aplicação para suportar um novo toolset para cada novo modelo. O MCP Gateway resolve isto.
Primeiro, vamos separar MCP de A2A, ou routing Agent-to-Agent. Uma confusão comum é tratá-los como a mesma coisa. A2A é quando fazes o routing de um prompt do utilizador para um agente externo especializado para gerar uma resposta de texto. MCP é completamente diferente. MCP significa Model Context Protocol, e trata-se de fornecer um conjunto standard de tools a um modelo, permitindo que esse modelo decida quando e como as invocar para concluir uma tarefa.
A feature MCP Gateway permite que o proxy LiteLLM atue como uma ponte entre qualquer modelo de linguagem e os teus servidores MCP. Em vez de escreveres código para registar tools em cada aplicação cliente que constróis, defines essas tools centralmente no proxy. A partir desse ponto, qualquer modelo que aceda ao proxy pode utilizar essas tools.
O LiteLLM liga-se a servidores MCP usando dois métodos principais. O primeiro é STDIO, ou Standard Input and Output. Isto é usado para tools locais. Configuras o proxy para executar um comando local específico, como correr um script Node ou um ficheiro Python, diretamente na máquina host. O segundo método é HTTP com Server-Sent Events, ou SSE. Isto é usado para ligar a servidores MCP remotos através de uma rede.
Vamos ver um cenário concreto. Queres adicionar um servidor MCP Zapier remoto para que os teus modelos possam interagir com web apps externas. Fazes isto inteiramente dentro do ficheiro YAML de configuração do proxy. No bloco de configuração principal, adicionas uma secção de servidores MCP. Dás um nome à integração, por exemplo, zapier-integration. Defines o tipo de transporte como SSE. A seguir, forneces o URL do endpoint do teu servidor MCP Zapier. Como se trata de uma ligação remota, também vais especificar os headers de autenticação necessários, como um bearer token, diretamente nesta definição YAML.
Agora o proxy sabe como falar com o Zapier. O próximo passo é a execução. Quando a tua aplicação cliente envia um request standard de chat completion para o LiteLLM, só precisa de incluir um header específico a indicar quais as tools MCP que quer carregar.
Aqui está o ponto-chave. A aplicação cliente não precisa de saber que tools o Zapier realmente oferece. O proxy interceta o request do cliente, liga-se ao servidor MCP do Zapier através da ligação SSE e vai buscar dinamicamente a lista atual de tools disponíveis. O proxy depois injeta essas definições de tools no payload e reencaminha todo o pacote para o modelo de linguagem.
Se o modelo de linguagem decidir invocar uma tool do Zapier, envia um tool call de volta para o proxy. O proxy apanha-o, executa a ação contra o servidor MCP do Zapier, obtém o resultado e devolve-o ao modelo. A tua aplicação cliente fica completamente blindada desta negociação de ida e volta. Recebe simplesmente tool responses standard compatíveis com a OpenAI.
O verdadeiro poder do MCP Gateway é desacoplar a implementação da tool da escolha do modelo, o que significa que uma integração construída para um ecossistema funciona instantaneamente em dezenas de modelos diferentes sem escrever código de adapter customizado.
Obrigado por ouvirem, happy coding a todos!
22
A2A: Rastrear Agentes Autónomos
3m 40sColoque os agentes autónomos sob controlo. Saiba como invocar agentes complexos do LangGraph ou Bedrock através do proxy usando o protocolo A2A, permitindo o agrupamento de traces e a monitorização unificada de gastos.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: The Universal LLM Gateway, episódio 22 de 24.
Quando o teu agente autónomo entra num reasoning loop de cinquenta passos, como é que rastreias a conta até à request original? Se o agente fizer dezenas de calls isoladas para diferentes language models, os teus logs de faturação tornam-se numa confusão ilegível de requests desconectadas. A solução para isto é o LiteLLM Agent Gateway, também conhecido como protocolo A2A.
Antes de explorarmos a mecânica, devemos esclarecer uma confusão comum. Os ouvintes frequentemente confundem isto com o Model Context Protocol, ou MCP. O MCP é usado para fornecer external tools a um language model. O A2A faz exatamente o oposto. Trata um agente externo e autónomo como se fosse um standard language model, permitindo-te invocá-lo e rastreá-lo através de um gateway centralizado.
Para configurar isto, defines o teu agente no ficheiro de configuração do LiteLLM exatamente como definirias um standard language model. Dás um nome ao modelo, defines o base URL a apontar para o API endpoint do teu agente, e especificas o provider como um custom OpenAI endpoint. Agora, o LiteLLM sabe como encaminhar as client requests recebidas diretamente para o teu agente.
Quando um cliente envia uma request a pedir este agente, o LiteLLM atua como um pass through para os context headers. Pega nos metadados ligados à request, como identificadores de utilizador, tags de team routing e limites de orçamento, e empacota-os em HTTP headers específicos. O mais importante destes é o header X-LiteLLM-Trace-Id. O LiteLLM encaminha estes headers, juntamente com o prompt, para o teu agente.
Aqui está o ponto chave. O teu agente recebe esta request, inicia o seu loop autónomo e começa a fazer as suas próprias calls internas para processar a tarefa. Se o agente fizer estas calls diretamente para um provider público, perdes o contexto de tracking. Em vez disso, o agente deve encaminhar as suas calls internas de volta através do LiteLLM. Ao fazer isto, deve incluir o trace ID que recebeu na request original.
Considera um cenário concreto. Estás a invocar um agente LangGraph local. Um cliente envia um prompt através do LiteLLM para iniciar o processo. O LiteLLM atribui um trace ID único e encaminha o payload para o endpoint do LangGraph. A tua aplicação LangGraph lê os HTTP headers recebidos e extrai o X-LiteLLM-Trace-Id. Quando o LangGraph precisa de avaliar um passo ou resumir dados, usa o seu cliente interno para enviar uma completion call de volta para o LiteLLM. Crucialmente, anexa esse exato mesmo trace ID header à sua outgoing request.
Como cada call interna carrega o mesmo trace identifier, o LiteLLM agrupa-as automaticamente. Ao olhares para a tua plataforma de observabilidade ou para os logs de orçamento, não vês cinquenta requests aleatórias de fontes desconhecidas. Vês um trace unificado. Sabes exatamente qual o utilizador que acionou o agente, quanto custou todo o reasoning loop, e quais os passos autónomos específicos que consumiram a maior parte do orçamento.
Tratar agentes como standard model endpoints transforma workflows de agentes complexos e de vários passos em unidades de computação rastreáveis e faturáveis.
Obrigado por ouvirem, happy coding a todos!
23
Rotações de Chaves com Zero-Downtime
3m 27sAlcance transições de segurança com zero-downtime. Saiba como configurar rotações de chaves automáticas programadas e grace periods para virtual keys de nível empresarial no LiteLLM.
Olá, daqui fala o Alex da DEV STORIES DOT EU. LiteLLM: The Universal LLM Gateway, episódio 23 de 24. Fazer a rotação de API keys de produção geralmente significa downtime programado, coordenação frenética e a esperança de que nenhum sistema de backend fique para trás com uma credencial expirada. Um hard cutover é uma medida de segurança rigorosa, mas também é uma forma altamente fiável de quebrar inflight requests. A solução para esta tensão são as Zero-Downtime Key Rotations.
Num setup de proxy empresarial, manter virtual keys estáticas para sempre é um risco de segurança inaceitável. O LiteLLM lida com isto permitindo-te agendar rotações automáticas de chaves. Em vez de gerares manualmente novas credenciais e coordenares um momento exato para as trocar, deixas o proxy gerir o lifecycle. Mas automatizar simplesmente a criação de uma nova chave não resolve o problema de fiabilidade subjacente. Se o gateway rejeitar imediatamente a chave antiga no segundo em que uma nova é criada, qualquer serviço que ainda não tenha sincronizado a nova credencial vai falhar instantaneamente.
Para corrigir isto, o LiteLLM usa um grace period. Quando crias ou atualizas uma virtual key, configuras dois parâmetros específicos. Primeiro, defines o intervalo de auto rotate, que determina exatamente com que frequência uma nova chave deve ser gerada. Segundo, defines o grace period, que diz ao sistema durante quanto tempo a chave antiga deve permanecer válida após a rotação ocorrer.
Considera uma arquitetura de microservices standard onde a tua política de segurança exige a rotação das chaves de acesso ao LLM a cada trinta dias. Fazes um request ao endpoint de geração de chaves do LiteLLM. Nesse request, defines o parâmetro de auto rotate para 30 dias. Exatamente no mesmo request, defines o parâmetro de grace period para 24 horas. O proxy guarda esta política e começa a contar o tempo.
Ao fim de trinta dias, a rotação é acionada. O LiteLLM gera automaticamente uma virtual key completamente nova. Esta é a parte que interessa. Durante as 24 horas seguintes, tens duas chaves completamente válidas a apontar exatamente para a mesma configuração, budget e lógica de tracking.
Durante esta janela de sobreposição, o teu secrets manager vai buscar a nova chave e injeta-a lentamente no teu ambiente de produção. À medida que os containers reiniciam ou os configuration maps são atualizados, os serviços mudam de forma independente para a nova credencial. Se um background worker específico ainda estiver a usar a chave antiga já com doze horas de grace period, o LiteLLM aceita o request sem reclamar. O gateway encaminha o tráfego para o large language model e regista a transação normalmente.
Assim que o grace period exato de 24 horas expira, o LiteLLM invalida automaticamente a chave original. Qualquer sistema restante que ainda tente usar a credencial antiga vai receber um erro de autenticação. A migração está concluída.
Desacoplaste completamente a criação do novo secret da destruição do antigo. Separar estes dois eventos transforma a rotação de chaves de um pânico de infraestrutura frágil e altamente coordenado, numa rotina de background silenciosa e fiável.
Obrigado por ouvirem, happy coding a todos!
24
A Admin UI e o AI Hub
3m 41sTorne a sua plataforma de IA acessível a todos. Saiba como gerir a Admin UI, ajustar credenciais da UI e usar o AI Hub para permitir que os developers descubram de forma segura os modelos e agentes permitidos.
Olá, daqui é o Alex da DEV STORIES DOT EU. LiteLLM: O Gateway LLM Universal, episódio 24 de 24. A tua equipa de plataforma construiu um gateway LLM altamente seguro e com routing perfeito. Mas quando os developers internos precisam realmente de construir algo, como é que sabem que modelos e agentes podem usar? Sem um mecanismo de discovery, o teu gateway é uma caixa negra invisível. Essa visibilidade é dada pela Admin UI e pelo AI Hub.
A Admin UI é um dashboard visual integrado diretamente no proxy LiteLLM. Operar um gateway LLM puramente através de ficheiros de configuração e queries à base de dados escala mal quando várias equipas começam a pedir acesso. A Admin UI dá aos operadores de plataforma um local centralizado para gerir o proxy. Através desta interface, podes gerar novas API keys, monitorizar o gasto de tokens entre diferentes equipas, acompanhar os logs de requests em tempo real e configurar regras de routing de modelos.
Quando inicias o proxy LiteLLM pela primeira vez, este dashboard vem ativado por default e protegido com credenciais de login default. Para testes locais, isto é conveniente. Para produção, é uma vulnerabilidade. Tens de alterar estas credenciais default imediatamente. Fazes isto definindo variáveis de ambiente específicas para o username e password de administração antes de iniciar o container.
Aqui está o ponto chave. Podes não querer ter um dashboard gráfico exposto de todo no teu gateway de produção. Muitas equipas de plataforma provisionam infraestrutura estritamente através de scripts automatizados e não querem um control plane interativo acessível pela rede. Se isso se encaixa no teu modelo de segurança, podes desativar o dashboard por completo. Ao definir uma variável de ambiente chamada disable admin ui para true, removes completamente a interface. O proxy vai continuar a fazer o routing do tráfego e a aplicar as regras, mas o web server não vai servir os ecrãs de administração.
Isto cobre a parte dos operadores de plataforma, mas os engenheiros que consomem a API precisam de uma perspetiva diferente. É aí que entra o AI Hub. Enquanto a Admin UI serve para controlo, o AI Hub serve para discovery. Funciona como um developer portal interno para a tua organização.
Em vez de enviarem mensagens à equipa de plataforma a perguntar que modelos estão atualmente aprovados ou onde vive a documentação de um agente interno, os developers visitam o AI Hub. Eles autenticam-se, tipicamente através do provider de single sign-on da tua organização, e é-lhes apresentado um catálogo. Podem ver exatamente que modelos estão autorizados a chamar, rever os rate limits aplicados a esses modelos, e descobrir agentes pré-configurados construídos por outras equipas.
Mais importante ainda, o AI Hub permite aos developers fazerem self-serve. Podem gerar as suas próprias API keys ligadas aos budgets específicos das suas equipas, sem terem de esperar que um engenheiro de plataforma provisione uma manualmente. Isto muda fundamentalmente a forma como a tua organização interage com a IA generativa. Faz a ponte entre os engenheiros de infraestrutura que protegem o gateway e os engenheiros de produto que constroem as aplicações.
O gateway só é útil se for acessível, e o AI Hub transforma um proxy bloqueado numa plataforma self-serve, permitindo que as tuas equipas de engenharia se movam rápido sem estourar o teu budget. Isto conclui a nossa série sobre o LiteLLM. Encorajo-te a explorar a documentação oficial, a experimentar estas configurações hands-on, e a visitar dev stories dot eu para sugerir tópicos para futuras séries. Obrigado por ouvires, e happy coding a todos!