PT ▾
Obter chave de API

Como implementar um LLM em Python com uma API hospedada

Para a maioria dos projetos, como implementar LLM em Python se resume a chamar um modelo hospedado via HTTP, não treiná-lo ou hospedá-lo você mesmo. Com uma API compatível com OpenAI, leva cerca de dez linhas, e o mesmo código cresce para streaming, saída JSON e chamada de funções.

Atualizado

Um terminal enviando um feixe para um servidor na nuvem e recebendo cubos de dados, ilustrando uma chamada Python para um LLM hospedado

Pontos principais

  • Instale o pacote openai, defina uma base URL e uma chave, e use o ID do modelo uncensored.
  • Streaming, modo JSON e chamada de funções são todos suportados e usam os argumentos padrão do SDK.
  • Mantenha o histórico de chat em uma lista e observe a janela de 100.000 tokens.
  • Trate HTTP 429 com uma nova tentativa curta; requisições falhas ou recusadas não são cobradas.

API hospedada ou seu próprio modelo

Existem duas maneiras de colocar um modelo de linguagem em um programa Python. Você pode executar os pesos você mesmo, o que significa uma GPU, uma pilha de serviço, escolhas de quantização e muito tempo de espera por downloads. Ou você pode enviar requisições para um modelo que outra pessoa já executa. A primeira rota faz sentido para pesquisa, isolamento rigoroso de dados ou volume alto e constante. A segunda se adapta a quase tudo o resto: um script, um bot, um recurso de produto, um protótipo que você quer funcionando até o almoço.

Este guia segue a segunda rota. O serviço aqui é uma API de texto hospedada e compatível com OpenAI com um único modelo de pesos abertos, executado por um provedor independente e ajustado para responder sem recusas de conteúdo para uso adulto legal. Não é uma API oficial de nenhum fornecedor de modelo. Como segue o formato de solicitação da OpenAI, o pacote padrão openai funciona, e também o requests simples se você preferir sem dependências.

Passo 1: instalar e fazer a primeira chamada

Instale o SDK e armazene sua chave em uma variável de ambiente, para que ela nunca caia no seu código-fonte.

pip install openai
export API_KEY="your-key-here"

Então crie um cliente com a base URL do serviço. As únicas coisas que você altera em comparação com qualquer outra configuração estilo OpenAI são a URL, a chave e o nome do modelo.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.fluxapikey.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 list comprehensions in two sentences."},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

Esse é um programa completo e funcional. O endpoint por trás dele é POST /v1/chat/completions, autenticado com Authorization: Bearer <key>, e GET /v1/models lista o ID do modelo. Você pode obter uma chave e um pequeno crédito de teste na página de chaves.

Passo 2: fazer streaming da resposta

Esperar vários segundos por uma resposta completa parece lento em um terminal ou em uma página web. Defina stream=True e imprima os tokens conforme chegam via eventos enviados pelo servidor.

# client from step 1: base_url https://api.fluxapikey.com/v1
stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short story opening about a lighthouse keeper."}],
    stream=True,
)

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

Os números de uso chegam no final do streaming, então o último chunk pode não ter choices. É por isso que o loop verifica chunk.choices primeiro. Uma coisa a lembrar: uma solicitação em streaming mantém seu slot de concorrência até o fim do streaming, então sempre leia até o fim ou feche.

Passo 3: manter uma conversa

O modelo não tem memória entre chamadas. Um chat é apenas uma lista crescente de mensagens que você reenvia cada vez. Uma pequena classe é suficiente:

# client from step 1: base_url https://api.fluxapikey.com/v1
class Chat:
    def __init__(self, system):
        self.messages = [{"role": "system", "content": system}]

    def say(self, text):
        self.messages.append({"role": "user", "content": text})
        r = client.chat.completions.create(model="uncensored", messages=self.messages)
        answer = r.choices[0].message.content
        self.messages.append({"role": "assistant", "content": answer})
        return answer

bot = Chat("You are a patient Python tutor.")
print(bot.say("What is a generator?"))
print(bot.say("Show me one with yield."))

A janela de contexto tem 100.000 tokens, compartilhada pelo prompt e pela conclusão. Isso é espaçoso, mas um chat longo cresce a cada turno, e você paga pelo histórico inteiro em cada solicitação. Quando fica grande, remova os turnos mais antigos ou substitua-os por um resumo curto que você pede ao modelo para escrever.

Passo 4: obter saída estruturada

Programas querem dados, não parágrafos. O modo JSON torna a resposta JSON válida. Diga no prompt quais chaves você espera.

# client from step 1: base_url https://api.fluxapikey.com/v1
import json

r = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": 'Return JSON like {"title": str, "tags": [str]}.'},
        {"role": "user", "content": "Summarise: a tutorial on async IO in Python."},
    ],
)
data = json.loads(r.choices[0].message.content)
print(data["title"], data["tags"])

JSON válido não garante suas chaves. Verifique-as no código e tente novamente uma vez se uma estiver faltando.

Passo 5: permitir que o modelo chame suas funções

A chamada de funções permite que o modelo peça ao seu programa para executar uma função, e depois continue com o resultado. Você descreve a ferramenta, verifica se a resposta contém uma chamada, executa-a e envia a saída de volta com o role tool.

# client from step 1: base_url https://api.fluxapikey.com/v1
import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_word_count",
        "description": "Count the words in a text.",
        "parameters": {
            "type": "object",
            "properties": {"text": {"type": "string"}},
            "required": ["text"],
        },
    },
}]

messages = [{"role": "user", "content": "How many words are in: the quick brown fox?"}]
r = client.chat.completions.create(model="uncensored", messages=messages, tools=tools, tool_choice="auto")
msg = r.choices[0].message

if msg.tool_calls:
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = len(args["text"].split())
        messages.append({"role": "tool", "tool_call_id": call.id, "content": str(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

Sempre valide os argumentos antes de agir com base neles, porque o modelo pode produzir uma chamada que você não esperava. As chamadas de ferramentas também fazem streaming, como deltas de tool_calls, se você precisar disso. A documentação lista todos os campos.

Passo 6: lidar com limites e erros

Uma chave completa permite 8 solicitações simultâneas e 300 por minuto; uma chave de teste permite 2 e 60. Ultrapasse e a API responde HTTP 429. O código de erro é rate_limited para muitas solicitações por minuto e concurrency para muitas de uma vez. Em sobrecarga temporária você também recebe um 429, com um cabeçalho Retry-After: 5. Um pequeno wrapper de tentativas cobre os três casos:

# client from step 1: base_url https://api.fluxapikey.com/v1
import time
from openai import RateLimitError

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

Se você executar trabalho em threads, limite-as a 8 com um ThreadPoolExecutor(max_workers=8) para raramente atingir o limite de concorrência. Cada resposta carrega X-Request-Id, que é o que você deve citar se entrar em contato com o suporte, e X-Balance-USD mostra seu crédito restante. O tamanho máximo do corpo é 8 MB.

Configurações que alteram a saída

A maior parte do ajuste do dia a dia acontece em um punhado de parâmetros, todos passados para o modelo.

  • temperature controla a aleatoriedade. Use 0.2 ou menos para extração e classificação, cerca de 0.7 para chat, e 1.0 ou mais para brainstorming e ficção.
  • top_p reduz a cauda improvável das escolhas de palavras. Altere top_p ou a temperatura, não os dois, não ambos ao mesmo tempo, para que você possa identificar qual deles fez o efeito.
  • seed torna as execuções repetidas mais comparáveis. É útil em testes onde você quer ver o efeito de uma mudança de prompt e não o ruído.
  • stop termina a geração em uma string que você escolher, o que é útil para cortar um modelo que continua adicionando comentários.
  • max_tokens é opcional. Sem ele, a conclusão pode usar o que sobrar da janela de 100.000 tokens. Defina-o quando quiser um limite rígido de comprimento e custo.
  • As penalidades de frequência e presença desencorajam a repetição, o que ajuda com a saída criativa longa que começa a entrar em loop.

Anote as configurações que você usou ao lado de qualquer saída com a qual você se importe. Meses depois, "por que respondeu de forma diferente" é quase sempre um parâmetro alterado ou uma mensagem de sistema alterada.

Executando muitas requisições de uma vez

Um loop que envia uma solicitação por vez desperdiça a maior parte da sua cota. Com uma chave completa, você pode ter 8 solicitações em andamento, então um pool de threads reduz um lote longo para aproximadamente um oitavo do tempo de relógio.

from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.fluxapikey.com/v1", api_key="YOUR_KEY")

def summarise(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarise in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

texts = ["first document", "second document", "third document"]
with ThreadPoolExecutor(max_workers=8) as pool:
    for line in pool.map(summarise, texts):
        print(line)

Mantenha a contagem de workers em 8 ou menos, ou em 2 em uma chave de teste. Se você ainda vir respostas 429 com o código concurrency, reduza o número em um ou dois. O limite de 300 por minuto importa para solicitações rápidas e curtas, então um lote de chamadas pequenas pode atingir esse limite antes do limite de concorrência.

Problemas comuns e soluções

A maioria dos erros do primeiro dia vem de uma lista curta de causas.

  • 401 ou erro de autenticação. A chave está ausente, digitada incorretamente ou enviada para o host errado. Imprima a base URL que seu cliente realmente usa e certifique-se de que ela termina em /v1.
  • Modelo não encontrado. O ID do modelo deve ser uncensored. Chame GET /v1/models se quiser confirmar o que o servidor lista.
  • Resposta vazia ou cortada. Um max_tokens baixo interrompe a resposta no meio da frase. Aumente-o ou remova-o. Verifique finish_reason na escolha: length significa que o limite foi atingido.
  • JSON que não pode ser analisado. Ou a resposta foi truncada, ou o prompt nunca descreveu a forma. Corrija o prompt primeiro e envolva a análise em um bloco try.
  • Primeiro token lento. Um prompt muito longo leva mais tempo para ser processado. Reduza o histórico ou envie menos contexto.
  • Solicitação muito grande. O limite do corpo é 8 MB, e a janela de tokens é 100.000. Divida documentos grandes em partes e resuma cada uma.

Quando algo ainda parecer errado, registre o cabeçalho X-Request-Id com a entrada falha. Isso permite que o suporte encontre a solicitação exata.

Quanto custa

Você paga $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída a partir do crédito pré-pago. Uma chamada típica com 2.000 tokens de entrada e 500 de saída custa 0,002 x $0,15 = $0,0003 para entrada mais 0,0005 x $0,50 = $0,00025 para saída, totalizando $0,00055. Dez mil chamadas assim custam $5,50. Solicitações falhas ou recusadas não são cobradas e o crédito nunca expira. Recargas variam de $20 a $500; veja preços para os níveis de bônus. Prompts não são usados para treinamento.

Tokens de saída custam mais que tokens de entrada, então o hábito mais econômico é pedir respostas curtas: diga duas frases, ou apenas JSON, e defina max_tokens para um teto sensato. Leia resp.usage durante o desenvolvimento para ver as contagens reais de tokens para seus prompts, e multiplique pelas taxas acima antes de escalar um trabalho. O cabeçalho X-Balance-USD mostra o que resta após cada chamada.

Perguntas e respostas

Preciso de uma GPU para implementar um LLM em Python?

Não com uma API hospedada. Seu código Python apenas envia requisições HTTP, então qualquer laptop funciona.

Posso usar o pacote oficial openai?

Sim. Defina base_url para a URL do serviço e api_key para sua chave, e use o ID do modelo uncensored.

Suporta código assíncrono?

O cliente AsyncOpenAI do SDK funciona com a mesma URL base e chave. Mantenha a concorrência em 8 ou menos requisições.

Como testar sem pagar?

Cadastre-se e resgate o crédito de teste de $0,50 na página de chaves. Ele é válido por 7 dias e não precisa de cartão.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de API