Como Usar o LiteLLM com o Ollama

Grandes Modelos de Linguagem (LLMs) estão transformando a maneira como construímos aplicações, mas confiar apenas em APIs baseadas em nuvem nem sempre é ideal. Latência, custo, privacidade de dados e a necessidade de capacidades offline frequentemente levam os desenvolvedores a executar modelos localmente. Ollama surgiu como uma ferramenta fantástica para executar facilmente poderosos LLMs de código aberto como Llama 3, Mistral e Phi-3 diretamente em sua máquina (macOS, Linux, Windows).

No entanto, interagir com diferentes LLMs, sejam locais ou remotos, frequentemente exige escrever código específico para cada modelo. É aqui que o LiteLLM entra. O LiteLLM fornece uma interface padronizada e leve para interagir com mais de 100 diferentes APIs de LLM, incluindo Ollama, OpenAI, Anthropic, Cohere e muitos outros. Ao usar o LiteLLM, você pode escrever o código uma vez e alternar perfeitamente entre diferentes modelos e provedores — incluindo seus modelos Ollama em execução localmente — com mudanças mínimas.

Este tutorial oferece um guia detalhado, passo a passo, sobre como configurar e usar o LiteLLM para interagir com os modelos Ollama em execução em sua máquina local. Vamos cobrir tudo, desde a instalação e configuração básica até a realização de chamadas de API, transmissão de respostas e uso de recursos mais avançados do LiteLLM.

💡

Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e All-in-One para sua equipe de desenvolvimento trabalhar em conjunto com máxima produtividade?

Apidog atende todas as suas demandas e substitui Postman a um preço muito mais acessível!

button

Introdução: Por que LiteLLM e Ollama?

Antes de mergulhar nos passos técnicos, vamos entender as ferramentas com as quais estamos trabalhando e por que a combinação delas é poderosa.

O que é LiteLLM?

LiteLLM é uma biblioteca Python leve que atua como uma interface unificada para interagir com uma vasta gama de APIs de LLM. Em vez de aprender e implementar diferentes SDKs ou formatos de requisição de API para OpenAI, Anthropic, Cohere, Google Gemini, Azure OpenAI, Replicate, Hugging Face, e modelos locais como Ollama, você usa uma única chamada de função consistente: litellm.completion(). LiteLLM lida com a complexidade subjacente de traduzir sua solicitação para o formato específico exigido pelo provedor do modelo alvo.

Principais Recursos do LiteLLM:

Interface Unificada: Chamadas de API consistentes (litellm.completion, litellm.embedding) em mais de 100 provedores de LLM.
Independência de Provedor: Altere facilmente entre modelos (por exemplo, de gpt-4o para ollama/llama3) mudando uma única string de modelo.
Robustez: Suporte integrado para timeouts, tentativas e fallback.
Observabilidade: Registro integrado, callbacks e suporte para plataformas como Langfuse, Helicone e PromptLayer.
Servidor Proxy: Oferece um servidor proxy autônomo para gerenciamento centralizado de chaves de API, balanceamento de carga, roteamento e acesso consistente em diferentes aplicativos ou serviços.
Rastreamento de Custos: Ajuda a monitorar gastos em várias APIs de LLM.

Por que usar LiteLLM com Ollama?

A combinação de Ollama e LiteLLM oferece várias vantagens:

Padronização: Escreva a lógica da aplicação usando a interface padrão do LiteLLM, permitindo que você alterne perfeitamente entre um modelo Ollama local (para desenvolvimento, privacidade, uso offline) e um poderoso modelo em nuvem (para produção, capacidades específicas) sem reescrever o código central.
Integração Local Simplificada: LiteLLM torna a interação com a API do Ollama direta dentro de suas aplicações Python, lidando com formatação de requisições e análise de respostas.
Flexibilidade: Experimente facilmente diferentes modelos locais disponíveis através do Ollama apenas mudando o nome do modelo na sua chamada do LiteLLM (por exemplo, ollama/llama3 vs. ollama/mistral).
Utilize os Recursos do LiteLLM: Beneficie-se de recursos do LiteLLM como tentativas, fallback, registro e rastreamento de custos, mesmo ao usar modelos Ollama locais.
Abordagens Híbridas: Construa aplicações que podem rotear inteligentemente requisições para modelos Ollama locais ou APIs remotas com base em fatores como custo, latência ou requisitos de tarefa, tudo gerenciado através do LiteLLM (especialmente via seu proxy).

Preparando-se para usar LiteLLM e Ollama

Antes de começarmos, certifique-se de que você tem as ferramentas necessárias instaladas e configuradas.

LiteLLM é uma biblioteca Python, então você precisa do Python instalado em seu sistema. O LiteLLM requer Python 3.8 ou superior.

Verifique a Instalação: Abra seu terminal ou prompt de comando e execute:

python --version
# ou
python3 --version

Instalação: Se você não tiver o Python ou precisar de uma versão mais nova, baixe-o do site oficial do Python (python.org) ou use um gerenciador de pacotes como Homebrew (macOS), apt (Debian/Ubuntu) ou Chocolatey (Windows).
Pip: Certifique-se de que você tem pip, o instalador de pacotes Python. Ele geralmente vem empacotado com o Python. Você pode verificar com pip --version ou pip3 --version.

Instale e Configure o Ollama

Você precisa ter o Ollama instalado e em execução na mesma máquina onde planeja executar seu código Python do LiteLLM (ou acessível pela rede se estiver rodando em uma máquina diferente).

Baixar e Instalar: Visite o site do Ollama (ollama.com) e baixe o instalador para seu sistema operacional (macOS, Linux, Windows). Siga as instruções de instalação.
Verifique a Instalação: Após a instalação, abra uma janela de terminal nova e execute:

ollama --version

Isso deve exibir a versão instalada do Ollama.

Puxando um Modelo Ollama

Ollama precisa de pelo menos um modelo baixado para poder atender a requisições. Vamos puxar um modelo popular como Llama 3 (variante 8B instruct).

Comando Pull: No seu terminal, execute:

ollama pull llama3

Isso fará o download dos arquivos do modelo Llama 3. Pode levar algum tempo dependendo da sua conexão de internet e do tamanho do modelo. Você pode substituir llama3 por outros modelos disponíveis na biblioteca Ollama (por exemplo, mistral, phi3, gemma:2b). Consulte o site do Ollama para uma lista completa.

Instale o LiteLLM

Com Python e Ollama prontos, instale o LiteLLM usando pip.

Comando de Instalação: Abra seu terminal ou prompt de comando e execute:

pip install litellm
# ou se você usar pip3
# pip3 install litellm

Verificação (Opcional): Você pode verificar a instalação importando o LiteLLM em um interpretador Python:

python # ou python3
>>> import litellm
>>> litellm.__version__
# Isso deve imprimir a versão instalada sem erros.
>>> exit()

Execute o Ollama Localmente

LiteLLM precisa se conectar ao servidor API do Ollama. Você precisa garantir que o Ollama está em execução.

Verificando se o Ollama está em Execução

Aplicativos Desktop macOS/Windows: Se você instalou o aplicativo desktop, o Ollama geralmente é executado automaticamente em segundo plano após a instalação. Você deve ver um ícone do Ollama na sua barra de menu (macOS) ou na bandeja do sistema (Windows).
Linux / Início Manual: No Linux, ou se você preferir controle manual, pode ser necessário iniciar o servidor do Ollama explicitamente. Abra um terminal e execute:

ollama serve

Este comando iniciará o servidor, e ele geralmente permanecerá em execução naquela janela de terminal até que você o pare (Ctrl+C). Você pode querer executar isso em segundo plano ou como um serviço do sistema para uso a longo prazo.

Verificar Status: Você pode verificar se o servidor está responsivo tentando acessar seu ponto de extremidade padrão usando curl (se disponível) ou um navegador:

curl http://localhost:11434

Você deve receber uma resposta como Ollama is running. Se você receber um erro "conexão recusada", o Ollama provavelmente não está em execução ou está configurado em uma porta/endereço diferente.

Por padrão, o Ollama expõe sua API em:

URL: http://localhost:11434

LiteLLM está pré-configurado para saber esse endereço padrão. Se sua instância do Ollama estiver rodando em um host ou porta diferentes (por exemplo, dentro de um contêiner Docker com mapeamento de porta, ou em um servidor remoto), você precisará informar ao LiteLLM onde encontrá-lo (coberto na seção de Configuração). Para a maioria das configurações locais padrão, o padrão funciona imediatamente.

Faça sua Primeira Chamada LiteLLM para Ollama

Agora, vamos escrever um script Python simples para enviar uma requisição ao modelo llama3 em execução via Ollama, usando o LiteLLM.

Script Python Básico

Crie um novo arquivo Python (por exemplo, ollama_test.py) e adicione o seguinte código:

import litellm
import os

# Opcional: Defina o registro de logs verbose para o LiteLLM para ver o que está acontecendo
# litellm.set_verbose = True

# Defina o nome do modelo - importante: prefixe com "ollama/"
# Garanta que 'llama3' é o modelo que você puxou com `ollama pull llama3`
model_name = "ollama/llama3"

# Defina as mensagens para a conclusão do chat
messages = [
    {"role": "system", "content": "Você é um assistente útil."},
    {"role": "user", "content": "Por que o céu é azul?"}
]

try:
    print(f"--- Enviando requisição para {model_name} ---")
    # Chame a função litellm.completion
    response = litellm.completion(
        model=model_name,
        messages=messages
    )

    # Imprima a resposta
    print("--- Resposta ---")
    # O objeto de resposta espelha a estrutura da API do OpenAI
    # Acesse o conteúdo da mensagem assim:
    message_content = response.choices[0].message.content
    print(message_content)

    # Você também pode imprimir o objeto de resposta completo para inspeção
    # print("\n--- Objeto de Resposta Completo ---")
    # print(response)

except Exception as e:
    print(f"Ocorreu um erro: {e}")

Vamos decompor a função:

litellm.completion(): Esta é a função central no LiteLLM para gerar conclusões de texto (incluindo conclusões no estilo chat).
model: Este parâmetro especifica qual modelo/provedor usar. Criticamente, para modelos Ollama, você deve prefixar o nome do modelo (conhecido pelo Ollama) com ollama/. Assim, llama3 se torna ollama/llama3, mistral se torna ollama/mistral, etc. Isso informa ao LiteLLM para direcionar a solicitação para um ponto de extremidade compatível com o Ollama.
messages: Isso segue o formato padrão de conclusão de chat do OpenAI — uma lista de dicionários, cada um com um role (system, user ou assistant) e content.
Valor de Retorno: O objeto response retornado por litellm.completion imita a estrutura do objeto de resposta da API do OpenAI. Essa consistência é um benefício chave do LiteLLM. Você normalmente acessa o texto gerado através de response.choices[0].message.content.

Com esses pontos em mente, vamos executar a função:

Certifique-se de que o Ollama está em execução (como verificado na Etapa 4) e que você puxou o modelo llama3. Então, execute o script a partir do seu terminal:

python ollama_test.py

Você deve ver uma saída semelhante a esta (o texto exato variará com base na resposta do modelo):

--- Enviando requisição para ollama/llama3 ---
--- Resposta ---
O céu parece azul por causa de um fenômeno chamado dispersão de Rayleigh. A luz solar que chega à atmosfera da Terra é composta por diferentes cores de luz, que têm comprimentos de onda diferentes. A luz azul e violeta têm comprimentos de onda mais curtos, enquanto a luz vermelha e laranja têm comprimentos de onda mais longos.

À medida que a luz solar passa pela atmosfera, ela colide com pequenas moléculas de gás (principalmente nitrogênio e oxigênio). Essas moléculas dispersam a luz solar em todas as direções. Comprimentos de onda mais curtos (azul e violeta) são espalhados de forma mais eficaz do que comprimentos de onda mais longos (vermelho e laranja).

Nossos olhos são mais sensíveis ao azul do que ao violeta, e parte da luz violeta é absorvida mais acima na atmosfera, então percebemos o céu como predominantemente azul durante o dia, quando o sol está alto.

Perto do nascer e do pôr do sol, a luz solar passa por mais da atmosfera para alcançar nossos olhos. A maior parte da luz azul é dispersada, permitindo que mais da luz vermelha e laranja de comprimento de onda mais longo chegue até nós, razão pela qual os nasceres e pores do sol costumam parecer avermelhados ou alaranjados.

Parabéns! Você usou com sucesso o LiteLLM para se comunicar com seu modelo local do Ollama.

Faça Respostas em Streaming

Para aplicações interativas (como chatbots) ou ao gerar respostas longas, esperar pela conclusão inteira pode levar a uma má experiência do usuário. O streaming permite que você receba a resposta token por token à medida que é gerada. O LiteLLM torna isso fácil.

Por que Streaming?

Melhoria na Performance Percebida: Os usuários veem a saída imediatamente, tornando a aplicação mais responsiva.
Manipulação de Respostas Longas: Processe partes da resposta sem esperar pela completude, útil para a geração de textos muito longos.
Interação em Tempo Real: Permite construir interfaces conversacionais em tempo real.

Implementando Streaming com LiteLLM

Modifique o script anterior (ollama_test.py) para habilitar o streaming:

import litellm
import os

# litellm.set_verbose = True # Opcional para depuração

model_name = "ollama/llama3"
messages = [
    {"role": "system", "content": "Você é um poeta conciso."},
    {"role": "user", "content": "Escreva um haikai curto sobre um gato."}
]

try:
    print(f"--- Enviando requisição de streaming para {model_name} ---")
    # Defina stream=True
    response_stream = litellm.completion(
        model=model_name,
        messages=messages,
        stream=True  # Ativar streaming
    )

    print("--- Resposta em Streaming ---")
    full_response = ""
    # Itera pelos chunks do stream
    for chunk in response_stream:
        # Cada chunk imita a estrutura do chunk de streaming do OpenAI
        # Acesse o conteúdo delta assim:
        content_delta = chunk.choices[0].delta.content

        if content_delta:  # Verifique se há novo conteúdo neste chunk
            print(content_delta, end="", flush=True) # Imprima imediatamente sem nova linha
            full_response += content_delta

    print("\n--- Fim do Stream ---")
    # print(f"\nResposta completa reconstruída:\n{full_response}") # Opcional: mostre a resposta completa no final

except Exception as e:
    print(f"\nOcorreu um erro: {e}")

Alterações:

stream=True: Adicionado este parâmetro à chamada litellm.completion.
Iteração: A função agora retorna um iterador (response_stream). Loop através deste iterador.
Manipulação do Chunk: Cada chunk no loop representa uma pequena parte da resposta. Acesse o novo fragmento de texto usando chunk.choices[0].delta.content. O atributo delta contém a diferença do chunk anterior (geralmente alguns caracteres ou uma palavra).
print(..., end="", flush=True): Imprime o conteúdo do chunk imediatamente sem adicionar uma nova linha, esvaziando o buffer de saída para garantir que apareça no terminal imediatamente.

Execute este script atualizado:

python ollama_test.py

Você verá o haikai aparecer palavra por palavra ou caractere por caractere no seu terminal, demonstrando o comportamento de streaming.

Configurando a Configuração do LiteLLM + Ollama

Enquanto o LiteLLM funciona com configurações padrão do Ollama imediatamente, você pode precisar configurá-lo se sua configuração se desviar do padrão http://localhost:11434.

Comportamento Padrão (Localhost)

Como mencionado, o LiteLLM assume automaticamente que o Ollama está em execução em http://localhost:11434 quando você usa o prefixo ollama/. Se esta é a sua configuração, nenhuma configuração adicional é necessária.

Usando Variáveis de Ambiente (Opcional)

Se o Ollama estiver rodando em um host ou porta diferentes, você pode informar ao LiteLLM onde encontrá-lo usando variáveis de ambiente. O LiteLLM verifica variáveis de ambiente específicas para configurar pontos de extremidade da API. Para um modelo específico do Ollama (ou todos os modelos do Ollama se você quiser uma substituição geral), você pode definir sua URL base.

Por exemplo, se sua instância do Ollama estiver rodando em http://192.168.1.100:11434, você pode definir uma variável de ambiente antes de executar seu script Python:

Linux/macOS:

export OLLAMA_API_BASE="http://192.168.1.100:11434"
python your_script.py

Windows (Prompt de Comando):

set OLLAMA_API_BASE=http://192.168.1.100:11434
python your_script.py

Windows (PowerShell):

$env:OLLAMA_API_BASE = "http://192.168.1.100:11434"
python your_script.py

Agora, quando seu script chamar litellm.completion(model="ollama/llama3", ...), o LiteLLM procurará a variável de ambiente OLLAMA_API_BASE e usará essa URL em vez do padrão localhost.

Nota: Definir OLLAMA_API_BASE sobrepõe a URL base para todos os modelos que começam com ollama/. Consulte a documentação do LiteLLM para controles de variáveis de ambiente mais granulares, se necessário (por exemplo, definir a URL base para um alias de modelo específico).

Usando um Arquivo de Configuração (Opcional)

Para configurações mais complexas envolvendo múltiplos modelos, configurações personalizadas ou evitando variáveis de ambiente, o LiteLLM suporta um arquivo de configuração (config.yaml ou caminho especificado).

Crie um arquivo config.yaml no mesmo diretório que seu script (ou em outro lugar, apontando o LiteLLM para ele):

# config.yaml
model_list:
  - model_name: ollama/llama3 # O nome que você usa em litellm.completion
    litellm_params:
      model: ollama/llama3 # O identificador real do modelo para o provedor
      api_base: "http://localhost:11434" # Padrão, altere se necessário

  - model_name: ollama/mistral-remote # Exemplo: Alias para um Ollama remoto
    litellm_params:
      model: ollama/mistral # Ollama espera 'mistral'
      api_base: "http://192.168.1.100:11434"

  - model_name: gpt-4o-mini # Exemplo: Incluindo um modelo que não é do Ollama
    litellm_params:
      model: gpt-4o-mini
      api_key: "os.environ/OPENAI_API_KEY" # Lido de forma segura da variável de ambiente

general_settings:
  # Opcional: Defina configurações globais como timeouts
  # timeout: 300 # 5 minutos

# Você pode definir variáveis de ambiente personalizadas dentro do config também
environment_variables:
  OPENAI_API_KEY: "" # Defina placeholders ou chaves reais (menos seguro)

Para usar este arquivo de configuração, você precisa informar ao LiteLLM para carregá-lo, normalmente no início da sua aplicação:

import litellm
import os

# Carregue a configuração do config.yaml no diretório atual
# Você também pode fornecer um caminho absoluto: litellm.load_config("path/to/your/config.yaml")
try:
    litellm.load_config()
    print("Configuração do LiteLLM carregada com sucesso.")
except Exception as e:
    print(f"Aviso: Não foi possível carregar a configuração do LiteLLM. Usando configurações padrão. Erro: {e}")


# Agora você pode usar os nomes de modelo definidos na configuração
try:
    # Usando o padrão ollama/llama3 que pode captar a api_base da configuração
    response_local = litellm.completion(model="ollama/llama3", messages=[{"role": "user", "content": "Teste local"}])
    print("Resposta Local do Llama3:", response_local.choices[0].message.content[:50], "...") # Imprimir fragmento

    # Usando o alias definido para o modelo mistral remoto
    # response_remote = litellm.completion(model="ollama/mistral-remote", messages=[{"role": "user", "content": "Teste remoto"}])
    # print("Resposta Remota do Mistral:", response_remote.choices[0].message.content[:50], "...")

except Exception as e:
    print(f"Ocorreu um erro durante a conclusão: {e}")

O arquivo de configuração oferece uma maneira estruturada de gerenciar configurações para múltiplos modelos, incluindo instâncias do Ollama que podem estar rodando em diferentes máquinas.

Além das chamadas básicas e streaming, o LiteLLM oferece recursos que aumentam a robustez e observabilidade, que funcionam perfeitamente com o Ollama.

Alias de Modelos

Enquanto o arquivo de configuração permite definir aliases, você também pode registrá-los programaticamente. Isso é útil para simplificar nomes de modelo ou mapear nomes genéricos a modelos específicos do Ollama.

import litellm

# Defina um alias: mapeie "meu-local-llm" para "ollama/llama3"
litellm.register_model({
    "meu-local-llm": {
        "model": "ollama/llama3",
        # Você também pode especificar api_base aqui se necessário para este alias especificamente
        # "api_base": "http://localhost:11434"
    }
})

# Agora use o alias em sua chamada de conclusão
messages = [{"role": "user", "content": "Me fale sobre alias de modelos."}]
response = litellm.completion(model="meu-local-llm", messages=messages)

print(response.choices[0].message.content)

Tratamento de Erros e Tentativas

Problemas de rede ou questões temporárias do Ollama podem ocorrer. O LiteLLM possui lógica de tentativas integrada.

import litellm
import time

# Exemplo: Deixe o Ollama temporariamente indisponível (por exemplo, pare `ollama serve`)
print("Parando o Ollama por 10 segundos (se possível)... Você pode precisar fazer isso manualmente.")
# os.system("ollama stop") # Este comando pode não existir; parar manualmente é mais seguro
# time.sleep(10)
# print("Reiniciando o Ollama... Você pode precisar fazer isso manualmente.")
# os.system("ollama serve &") # Iniciar em segundo plano
# time.sleep(5) # Dê um tempo para iniciar

messages = [{"role": "user", "content": "O tratamento de tentativas funciona?"}]

try:
    # O LiteLLM irá automaticamente tentar novamente em erros de conexão específicos
    # Você pode configurar o número de tentativas, fator de espera, etc.
    response = litellm.completion(
        model="ollama/llama3",
        messages=messages,
        num_retries=3,       # Tentar até 3 tentativas
        timeout=10           # Defina um timeout para cada tentativa de requisição (segundos)
    )
    print("Sucesso após tentativas (ou na primeira tentativa):")
    print(response.choices[0].message.content)

except Exception as e:
    # Isso capturará erros que persistem após as tentativas (por exemplo, modelo não encontrado, erro de configuração)
    # Ou se todas as tentativas falharem para erros de conexão.
    print(f"Ocorreu um erro após as tentativas: {e}")

O LiteLLM tenta inteligentemente novamente erros comuns de rede transitórios. Você pode personalizar o comportamento de tentativas globalmente ou por chamada.

Registro e Callbacks

O LiteLLM fornece ganchos para registrar dados de requisição/resposta ou acionar funções personalizadas (callbacks) em chamadas bem-sucedidas ou erros. Isso é inestimável para monitoramento, depuração e rastreamento de custos (embora o rastreamento de custos seja menos relevante para o Ollama local, a menos que você atribua custos virtuais).

import litellm
import logging

# Configure o registro básico
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(message)s')
logger = logging.getLogger(__name__)

# Defina uma função de callback de sucesso simples
def log_success(kwargs, completion_response, start_time, end_time):
    """Registra detalhes sobre uma chamada bem-sucedida do LLM."""
    model = kwargs.get("model", "modelo_desconhecido")
    input_text = kwargs.get("messages", [])[-1]['content'] if kwargs.get("messages") else "N/A"
    output_text = completion_response.choices[0].message.content[:50] + "..." # Fragmento
    duration = (end_time - start_time).total_seconds()
    logger.info(f"Sucesso! Modelo: {model}, Duração: {duration:.2f}s, Entrada: '{input_text[:30]}...', Saída: '{output_text}'")

# Defina uma função de callback de falha simples
def log_failure(kwargs, exception, start_time, end_time):
    """Registra detalhes sobre uma chamada falha do LLM."""
    model = kwargs.get("model", "modelo_desconhecido")
    duration = (end_time - start_time).total_seconds()
    logger.error(f"Falha! Modelo: {model}, Duração: {duration:.2f}s, Erro: {exception}")


# Registre os callbacks com o LiteLLM
litellm.success_callback = [log_success]
litellm.failure_callback = [log_failure]

# Agora faça uma chamada - os callbacks serão acionados automaticamente
messages = [{"role": "user", "content": "Como os callbacks funcionam no LiteLLM?"}]
try:
    response = litellm.completion(model="ollama/llama3", messages=messages)
    # print(response.choices[0].message.content) # Você ainda pode usar a resposta
except Exception as e:
    pass # O callback de falha já tratou o registro

# Exemplo de uma chamada que pode falhar (por exemplo, modelo não puxado)
# try:
#     response_fail = litellm.completion(model="ollama/nonexistent-model", messages=messages)
# except Exception as e:
#     pass # O callback de falha registrará

Execute este script e você verá mensagens INFO ou ERROR registradas pelas suas funções de callback, fornecendo visibilidade nas interações com o LLM. O LiteLLM também se integra com plataformas como Langfuse, Helicone, PromptLayer, etc., para observabilidade mais avançada.

Gerenciando Chaves de API

Embora o Ollama em si normalmente não exija chaves de API para acesso local, se sua aplicação também usar provedores de nuvem (OpenAI, Anthropic, etc.) via LiteLLM, você precisará gerenciar essas chaves. O LiteLLM procura chaves em variáveis de ambiente padrão (por exemplo, OPENAI_API_KEY, ANTHROPIC_API_KEY) ou elas podem ser definidas no config.yaml ou passadas diretamente para a chamada completion (menos recomendada por questões de segurança). Usar um config.yaml ou variáveis de ambiente é a abordagem preferida.

Como Usar o Servidor Proxy do LiteLLM (Recomendado para Robustez)

Enquanto usar diretamente a biblioteca litellm em seu código Python é ótimo para scripts simples ou aplicações únicas, o Proxy do LiteLLM oferece uma solução mais robusta e escalável, especialmente para microsserviços ou quando várias aplicações precisam acessar LLMs (incluindo Ollama).

O que é o Proxy do LiteLLM?

O Proxy do LiteLLM é um servidor autônomo que você executa separadamente. Suas aplicações então fazem requisições API compatíveis com o OpenAI para o endpoint do Proxy. O Proxy, configurado com os detalhes do seu modelo (incluindo instâncias do Ollama, chaves de API para provedores de nuvem, etc.), gerencia o roteamento da requisição para o LLM subjacente correto, gerenciando chaves, aplicando limites de taxa, registrando, tentando novamente e mais.

Configurando o Proxy com Ollama

Instale as Dependências do Proxy:

pip install 'litellm[proxy]'

Crie um Arquivo de Configuração do Proxy (proxy_config.yaml):
Este arquivo informa ao proxy sobre seus modelos disponíveis.

# proxy_config.yaml
model_list:
  - model_name: local-llama3 # Como os usuários chamarão este modelo via proxy
    litellm_params:
      model: ollama/llama3 # Informa ao proxy que usa o driver do ollama para 'llama3'
      api_base: "http://localhost:11434" # Certifique-se de que isso aponte para o seu Ollama

  - model_name: local-mistral
    litellm_params:
      model: ollama/mistral
      api_base: "http://localhost:11434" # Supondo a mesma instância do Ollama

  # Exemplo: Adicionando um modelo OpenAI juntamente com o Ollama
  - model_name: cloud-gpt4o
    litellm_params:
      model: gpt-4o-mini
      api_key: "os.environ/OPENAI_API_KEY" # O Proxy lê a variável de ambiente

litellm_settings:
  # Opcional: Defina configurações de nível de proxy
  # drop_params: True # Remove parâmetros não suportados antes de enviar ao modelo
  # set_verbose: True # Ativa registro detalhado do proxy
  pass

# environment_variables: # Defina variáveis de ambiente para o proxy se necessário
#   OPENAI_API_KEY: "sua_chave_openai_aqui" # Menos seguro - prefira variáveis de ambiente reais

Execute o Servidor Proxy:
Abra um terminal, certifique-se de que sua variável de ambiente OPENAI_API_KEY está definida (se estiver usando modelos do OpenAI) e execute:

litellm --config /caminho/para/proxy_config.yaml --port 8000
# Substitua /caminho/para/proxy_config.yaml pelo caminho real
# --port 8000 especifica a porta que o proxy escuta (o padrão é 4000)

O servidor proxy será iniciado e registrará informações, indicando que está pronto para receber requisições.

Fazendo Chamadas Através do Proxy

Agora, em vez de usar litellm.completion diretamente, seu código de aplicação (que pode até estar em uma linguagem diferente) faz chamadas API padrão ao endpoint do proxy (http://localhost:8000 neste exemplo). Você pode usar a biblioteca openai do Python ou simples requests.

Usando a biblioteca openai:

Primeiro, instale-a: pip install openai

import openai
import os

# Aponte o cliente OpenAI para o endpoint do Proxy do LiteLLM
client = openai.OpenAI(
    base_url="http://localhost:8000", # URL do SEU Proxy do LiteLLM
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # Requerido pelo cliente OpenAI, mas o Proxy do LiteLLM ignora por padrão
)

# Defina as mensagens
messages = [
    {"role": "system", "content": "Você é um assistente impulsionado por proxy."},
    {"role": "user", "content": "Explique o benefício de usar um proxy para chamadas de LLM."}
]

try:
    print("--- Enviando requisição via Proxy do LiteLLM ---")
    # Use o nome do modelo definido em proxy_config.yaml ('local-llama3')
    response = client.chat.completions.create(
        model="local-llama3", # Use o alias do proxy_config.yaml
        messages=messages,
        stream=False # Defina como True para streaming via proxy
    )

    print("--- Resposta do Proxy ---")
    print(response.choices[0].message.content)

    # Exemplo de Streaming via Proxy
    print("\n--- Streaming via Proxy ---")
    stream_response = client.chat.completions.create(
        model="local-llama3",
        messages=messages,
        stream=True
    )
    for chunk in stream_response:
         if chunk.choices[0].delta.content is not None:
              print(chunk.choices[0].delta.content, end="", flush=True)
    print("\n--- Fim do Stream ---")


except openai.APIConnectionError as e:
    print(f"Erro de Conexão: Não foi possível conectar ao Proxy do LiteLLM em {client.base_url}. Está em execução?")
except openai.APIStatusError as e:
    print(f"Erro de API: Status={e.status_code}, Resposta={e.response}")
except Exception as e:
    print(f"Ocorreu um erro inesperado: {e}")

Benefícios da Abordagem do Proxy

Gerenciamento Centralizado: Gerencie todas as configurações de modelos (Ollama, OpenAI, etc.) e chaves de API em um único lugar.
Interface Padrão do OpenAI: Todas as suas aplicações interagem usando o formato familiar do SDK/API OpenAI, independentemente do modelo de backend.
Independência de Linguagem: Qualquer aplicação que possa fazer requisições HTTP pode usar o proxy.
Balanceamento de Carga/Roteamento: Configure regras de roteamento, fallback e balanceamento de carga entre várias implementações de modelos (incluindo múltiplas instâncias do Ollama).
Registro/Monitoramento Consistente: Registro centralizado e observabilidade em todas as chamadas do LLM.
Segurança: As chaves de API para provedores de nuvem são armazenadas de forma segura no servidor proxy, não distribuídas nas aplicações clientes.

Para qualquer coisa além de scripts simples, usar o Proxy do LiteLLM é altamente recomendado ao integrar o Ollama em um ecossistema maior.

Resolvendo Problemas Comuns

Aqui estão alguns problemas comuns que você pode encontrar e como corrigi-los:

Erros de Conexão (connection refused, timeout)

O Ollama Está em Execução? Verifique se o servidor Ollama está ativo (Etapa 4). Verifique os logs do Ollama para erros.
API Base Correta? Você tem certeza de que o Ollama está em http://localhost:11434? Se não, configure o LiteLLM usando variáveis de ambiente (OLLAMA_API_BASE) ou o arquivo de configuração (Etapa 7) ou a configuração do proxy (Etapa 9).
Problemas de Firewall? Se o Ollama estiver rodando em uma máquina diferente ou dentro do Docker, verifique se as regras de firewall permitem conexões para a porta do Ollama (padrão 11434) de onde seu código/proxy do LiteLLM está rodando.
Proxy do LiteLLM em Execução? Se estiver usando o proxy, certifique-se de que o comando litellm --config ... está em execução e acessível no host/porta especificados.

Erros de Modelo Não Encontrado (litellm.exceptions.NotFounderror, 404 Model Not Found)

Nome do Modelo Correto? Você usou o prefixo ollama/ (por exemplo, ollama/llama3) em sua chamada litellm.completion ou configuração do proxy?
Modelo Puxado no Ollama? Você realmente executou ollama pull <model_name> (por exemplo, ollama pull llama3)? Verifique com ollama list.
Erro de Digitação? Verifique a ortografia do nome do modelo em relação à saída de ollama list.
Alias do Proxy: Se estiver usando o proxy, certifique-se de que o nome do modelo em sua chamada de cliente (por exemplo