Como instalar um LLM em Python: local ou API

Dois significados de instalar um LLM

Quando as pessoas perguntam como instalar llm em python, geralmente querem dizer uma de duas coisas. A primeira é executar um modelo localmente: baixar pesos e carregá-los com uma biblioteca na sua própria CPU ou GPU. A segunda é instalar uma biblioteca cliente para que seu código Python possa conversar com um modelo que roda em outro lugar. Ambas são válidas, e a correta depende do seu hardware e do que você quer construir.

A rota da API é muito mais curta. Você executa pip install openai, aponta o cliente para uma base URL e chama o modelo. Sem pesos, sem drivers de GPU, sem planejamento de memória. O restante desta página dá os passos e o código para essa rota, com uma seção curta sobre a local para você comparar.

Instalação local ou API hospedada: como escolher

Pergunta	Instalação local	API Hospedada
O que você instala	Uma biblioteca de inferência mais os pesos do modelo	O pacote openai
Hardware	Memória e geralmente uma GPU dimensionada para o modelo	Qualquer máquina que possa fazer chamadas HTTPS
Custo	Seu hardware e eletricidade	Por token, a partir de crédito pré-pago
Funciona offline	Sim	Não
Tempo até a primeira resposta	Download, configuração, ajuste	Alguns minutos

A instalação local faz sentido se você precisa manter tudo em uma máquina, precisa trabalhar offline ou quiser experimentar os próprios pesos. Bibliotecas como as bindings de llama.cpp ou Hugging Face transformers são os pontos de partida usuais; verifique sua própria documentação para requisitos de hardware, já que isso depende do tamanho do modelo que você escolher.

A API faz sentido se você quer um resultado funcional rapidamente, seu laptop não consegue armazenar um modelo grande ou seu app precisa atender muitos usuários. Você paga por token em vez de comprar hardware. Para este serviço, isso é US$ 0,15 por 1M de tokens de entrada e US$ 0,50 por 1M de tokens de saída, sem assinatura. A página de preços tem os detalhes.

Passo 1: criar um ambiente virtual e instalar o pacote

Use um ambiente virtual para que a instalação fique limpa. Qualquer versão recente do Python 3 funciona com o pacote openai.

Copypython3 -m venv .venv
source .venv/bin/activate
pip install openai

A seguir, você precisa de uma chave. Cadastre-se na página de chaves de API com Google ou com e-mail e senha. Novos usuários podem reivindicar US$ 0,50 de crédito de teste lá com um clique, válido por 7 dias e sem cartão. Armazene a chave em uma variável de ambiente em vez de no seu arquivo de origem:

Copyexport API_KEY="paste-your-key-here"

Passo 2: fazer sua primeira chamada

O serviço é compatível com OpenAI, então as únicas alterações em um script OpenAI padrão são a base URL e o ID do modelo. O ID do modelo é uncensored.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.getaiapikey.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what a context window is in two sentences."},
    ],
    temperature=0.7,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Se isso imprimir uma resposta e duas contagens de tokens, a instalação está concluída. Para verificar se sua chave funciona e ver o ID do modelo, você também pode chamar GET /v1/models:

Copyfor m in client.models.list():
    print(m.id)

A mesma solicitação do shell, sem Python, é uma única chamada curl para https://api.getaiapikey.com/v1/chat/completions com o cabeçalho Authorization: Bearer seguido pela sua chave. O guia de início rápido mostra isso completo.

Passo 3: transmitir tokens conforme chegam

Esperar uma resposta longa terminar antes de imprimir qualquer coisa parece lento. Defina stream=True e o servidor envia tokens via eventos enviados pelo servidor. Você pode solicitar um resumo de uso no último chunk com stream_options.

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short scene set in a lighthouse."}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage.total_tokens, "tokens")

Um detalhe importante para produção: uma solicitação em streaming mantém seu slot de concorrência até o fim do stream. Uma chave completa permite 8 requisições simultâneas, então se seu app abrir muitos streams longos, feche-os quando o usuário desconectar.

Passo 4: modo JSON e chamada de funções

Para saída estruturada, defina response_format para um objeto JSON. Também diga ao modelo no prompt para responder em JSON, porque a configuração garante sintaxe JSON válida, mas não os nomes de campo que você deseja.

Copyimport json

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Reply only with JSON: {\"title\": string, \"tags\": [string]}"},
        {"role": "user", "content": "Give me a title and tags for a post about slow travel."},
    ],
    response_format={"type": "json_object"},
)
data = json.loads(resp.choices[0].message.content)
print(data["title"], data["tags"])

A chamada de funções segue o padrão padrão. Você descreve uma função, o modelo pode pedir para chamá-la, você a executa e envia o resultado de volta com role: "tool".

Copytools = [{
    "type": "function",
    "function": {
        "name": "get_time",
        "description": "Return the current time for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

messages = [{"role": "user", "content": "What time is it in Lisbon?"}]
first = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)

msg = first.choices[0].message
if msg.tool_calls:
    call = msg.tool_calls[0]
    messages.append(msg)
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps({"time": "14:05"}),
    })
    final = client.chat.completions.create(
        model="uncensored", messages=messages, tools=tools
    )
    print(final.choices[0].message.content)

Teste chamadas de funções em alguns prompts antes de confiar nelas. Qualquer modelo pode escolher a função errada ou preencher um argumento mal, então valide argumentos no seu próprio código antes de executar qualquer coisa com efeitos colaterais.

Passo 5: lidar com limites e erros

Chaves completas permitem 8 requisições simultâneas e 300 requisições por minuto. Chaves de teste permitem 2 e 60. Passar desses limites resulta em HTTP 429. O código de erro rate_limited significa muitas requisições por minuto, e concurrency significa muitas de uma vez. Em sobrecarga temporária, a API também retorna 429 com um cabeçalho Retry-After: 5.

O cliente Python do OpenAI tenta novamente algumas falhas por conta própria, mas um wrapper explícito mantém o comportamento óbvio:

Copyimport time
from openai import RateLimitError

def ask(messages, tries=4):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited after retries")

Cada resposta carrega X-Request-Id, X-Balance-USD e cabeçalhos de limite de taxa, que você pode registrar. Inclua o ID da solicitação se entrar em contato com o suporte. Requisições falhas ou recusadas não são cobradas, então tentar novamente não custa extra.

Planeje também os limites de tamanho. A janela de contexto é de 100.000 tokens, prompt mais conclusão, e o corpo máximo da requisição é 8 MB. Histórico de chat longo deve ser reduzido ou resumido antes de atingir esses números.

Quando a chamada não funciona

A maioria dos problemas de primeira execução vem de uma série de erros. Verifique estes na ordem antes de suspeitar de qualquer outra coisa.

• Base URL sem o caminho da versão. O valor deve terminar em /v1. O cliente adiciona /chat/completions a ele, então uma falta de /v1 envia a solicitação para a rota errada.
• Chave errada ou ausente. A chave vai no cabeçalho Authorization: Bearer, que o cliente constrói a partir de api_key. Se a variável de ambiente estiver vazia, o cliente ou gera um erro no início ou envia uma chave em branco. Imprima bool(os.environ.get("API_KEY")) para verificar.
• Um nome de modelo de outro serviço. O único ID de modelo aqui é uncensored. Nomes como os de outros tutoriais não corresponderão.
• Sem saldo. Olhe o cabeçalho X-Balance-USD. Um período de teste que passou dos 7 dias, ou um saldo gasto, precisa de um recarregamento a partir de US$ 20.
• Pacote antigo. Se um exemplo usa OpenAI( e o Python diz que não pode importar esse nome, você tem o pacote pré-1.0. Execute pip install --upgrade openai.

Para ver a resposta bruta incluindo cabeçalhos, use o wrapper de resposta bruta do cliente:

Copyraw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=5,
)
print(raw.headers.get("x-request-id"), raw.headers.get("x-balance-usd"))
completion = raw.parse()
print(completion.choices[0].message.content)

Isso imprime o ID da solicitação e seu saldo restante ao lado da resposta, que é uma verificação rápida de saúde que você pode executar de um job cron ou script de inicialização.

Usando-o de outras ferramentas

Como o endpoint segue o formato OpenAI, outras bibliotecas Python podem usá-lo com as mesmas duas configurações. Frameworks que aceitam uma base URL OpenAI personalizada só precisam de base_url e api_key. Para Node, o pacote oficial openai aceita os mesmos campos:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.getaiapikey.com/v1",
  apiKey: process.env.API_KEY,
});

const r = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Say hello in five words." }],
});
console.log(r.choices[0].message.content);

Este é um serviço apenas de texto: sem geração de imagem ou áudio, sem embeddings e sem fine-tuning. Se seu projeto precisa disso, combine esta API com outra ferramenta para essa parte. O modelo é um modelo de pesos abertos executado por um provedor independente e ajustado para responder sem recusas de conteúdo para uso adulto legal. Conteúdo sexual envolvendo menores de idade nunca é permitido.

Mais guias

• Chave de API LLM Grátis: O que o Crédito de Teste Cobre
• Chave de API LLM para um Bot do Discord: Guia de Configuração
• Lista de Verificação de API de IA