API LLM para Desenvolvedores: Guia Completo de Integração

Este guia cobre tudo o que um desenvolvedor precisa para integrar APIs LLM em aplicações de produção: autenticação, streaming, uso de ferramentas, embeddings, padrões RAG e gerenciamento de custos. Todos os exemplos usam o formato compatível com OpenAI e funcionam com APIMaster.ai.

Configuração

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_APIMASTER_KEY",
    base_url="https://apimaster.ai/v1",
)

Padrões Principais

1. Conclusão de Chat Básica

def ask(prompt: str, model: str = "claude-sonnet-4-6") -> str:
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

2. Prompt de Sistema + Conversa

class Conversation:
    def __init__(self, system: str, model: str = "claude-sonnet-4-6"):
        self.model = model
        self.messages = [{"role": "system", "content": system}]
    
    def send(self, user_msg: str) -> str:
        self.messages.append({"role": "user", "content": user_msg})
        resp = client.chat.completions.create(
            model=self.model,
            messages=self.messages,
        )
        reply = resp.choices[0].message.content
        self.messages.append({"role": "assistant", "content": reply})
        return reply

bot = Conversation("Você é um desenvolvedor Python experiente.")
print(bot.send("O que é o GIL?"))
print(bot.send("Como posso contorná-lo?"))

3. Streaming

def stream(prompt: str, model: str = "gpt-5.4"):
    with client.chat.completions.stream(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    ) as s:
        for text in s.text_stream:
            yield text

for chunk in stream("Explique async/await em Python"):
    print(chunk, end="", flush=True)

4. Saída Estruturada

from pydantic import BaseModel
from typing import List

class ExtractedData(BaseModel):
    entities: List[str]
    sentiment: str
    summary: str

import json

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": f"Extraia os dados e retorne JSON que corresponda a este esquema: {ExtractedData.schema()}"},
        {"role": "user", "content": "A Apple reportou receita recorde. O CEO Tim Cook chamou de excepcional."},
    ],
    response_format={"type": "json_object"},
)

data = ExtractedData(**json.loads(response.choices[0].message.content))
print(data.entities)    # ["Apple", "Tim Cook"]
print(data.sentiment)   # "positivo"

5. Uso de Ferramentas / Chamada de Função

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "execute_sql",
            "description": "Executar uma consulta SQL somente leitura",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "database": {"type": "string", "enum": ["users", "orders", "products"]},
                },
                "required": ["query", "database"],
            },
        },
    }
]

def handle_tool_call(tool_name: str, args: dict) -> str:
    # Sua implementação
    return json.dumps({"result": "dados simulados"})

def agent_loop(user_msg: str):
    messages = [{"role": "user", "content": user_msg}]
    
    while True:
        resp = client.chat.completions.create(
            model="gpt-5.4",
            messages=messages,
            tools=tools,
        )
        
        if resp.choices[0].finish_reason != "tool_calls":
            return resp.choices[0].message.content
        
        # Processar chamadas de ferramenta
        messages.append(resp.choices[0].message)
        for tc in resp.choices[0].message.tool_calls:
            result = handle_tool_call(tc.function.name, json.loads(tc.function.arguments))
            messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})

6. Embeddings

def embed(texts: list[str]) -> list[list[float]]:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts,
    )
    return [item.embedding for item in response.data]

# Similaridade semântica
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

vecs = embed(["Python é ótimo", "Eu amo Python", "Java é verboso"])
print(cosine_similarity(vecs[0], vecs[1]))  # Alto: ~0.95
print(cosine_similarity(vecs[0], vecs[2]))  # Menor: ~0.70

7. RAG (Geração Aumentada por Recuperação)

from typing import List

def rag_query(user_question: str, knowledge_base: List[str]) -> str:
    # Passo 1: Incorporar a pergunta
    q_embedding = embed([user_question])[0]
    doc_embeddings = embed(knowledge_base)
    
    # Passo 2: Encontrar documentos mais relevantes
    similarities = [cosine_similarity(q_embedding, d) for d in doc_embeddings]
    top_indices = sorted(range(len(similarities)), key=lambda i: similarities[i], reverse=True)[:3]
    context = "\n\n".join(knowledge_base[i] for i in top_indices)
    
    # Passo 3: Gerar resposta com contexto
    response = client.chat.completions.create(
        model="claude-sonnet-4-6",
        messages=[
            {"role": "system", "content": f"Responda usando apenas este contexto:\n\n{context}"},
            {"role": "user", "content": user_question},
        ],
    )
    return response.choices[0].message.content

8. Assíncrono para Alto Rendimento

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    api_key="YOUR_APIMASTER_KEY",
    base_url="https://apimaster.ai/v1",
)

async def process_batch(prompts: list[str]) -> list[str]:
    tasks = [
        async_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": p}],
            max_tokens=100,
        )
        for p in prompts
    ]
    responses = await asyncio.gather(*tasks)
    return [r.choices[0].message.content for r in responses]

# Processar 50 prompts concorrentemente
results = asyncio.run(process_batch(my_prompts))

Checklist de Produção

• Chaves de API em variáveis de ambiente, não no código fonte
• Lógica de retry com backoff exponencial para erros 429/500
• max_tokens definido para evitar custos descontrolados
• Streaming para respostas voltadas ao usuário >2 segundos
• Log de requisições com contagem de tokens para rastreamento de custos
• Limitador de taxa para permanecer dentro dos limites do provedor

Escolha o Modelo Certo

Caso de Uso	Modelo	Faixa de Custo
Prototipação	deepseek-v4-flash ou gpt-4o-mini	Muito baixo
Chatbot de produção	claude-haiku-4-5	Baixo
Assistente de código	deepseek-v4-flash ou claude-sonnet-4-6	Baixo–médio
Análise complexa	claude-sonnet-4-6	Médio
Pesquisa/raciocínio	claude-opus-4-8 ou o3	Alto

Perguntas Frequentes

O que é uma API LLM? Uma API LLM é uma interface HTTP que permite que seu código envie prompts de texto e receba respostas geradas por IA. Você envia um array messages; a API retorna uma conclusão. A maioria usa o formato Chat Completions da OpenAI.

Como escolher entre provedores de API LLM? Considere a capacidade do modelo (benchmarks), custo por token, latência e confiabilidade. Para a maioria dos casos de uso, DeepSeek V4 Flash (codificação de baixo custo), Claude Sonnet (escrita/análise) ou GPT-4o (multimodal) cobrem os caminhos comuns. O APIMaster permite trocar de provedor com uma linha.

O que é uma API compatível com OpenAI? Um endpoint que implementa o mesmo formato /v1/chat/completions que a OpenAI, permitindo que você use a biblioteca Python openai ou qualquer ferramenta compatível com OpenAI com modelos que não são da OpenAI.

Como lidar com erros de API LLM em produção? Capture RateLimitError (tente novamente com backoff), APIConnectionError (tente novamente) e InvalidRequestError (corrija o prompt). Use timeouts e circuit breakers para resiliência em produção.

Posso usar uma única chave de API para vários provedores LLM? Sim—o APIMaster fornece uma única chave e endpoint para GPT, Claude, DeepSeek e Gemini. Troque de modelo alterando o parâmetro model. Nenhuma chave ou SDK específico de provedor é necessário.

Obter acesso à API LLM → · Comparar modelos →