Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Agrupamento Inline: Até 10K Pedidos Sem Ficheiro

Aula 4 de 16 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. A Alternativa Leve ao Agrupamento por Ficheiro
  2. Agrupamento por Ficheiro vs. Agrupamento Inline
  3. Criação de uma Tarefa Inline
  4. Exemplo Prático: Classificação de Tickets
  5. Quando Escolher Cada Abordagem
  6. Pontos-chave

Atualizado a 3 de novembro de 2026: Atualização de 3 de novembro: files.download devolve uma resposta HTTP (httpx2.Response); leia o seu conteúdo com .read() antes de chamar .decode().

A Alternativa Leve ao Agrupamento por Ficheiro

O agrupamento inline permite submeter pedidos de lote diretamente na chamada à API, ignorando a etapa de carregamento de ficheiros. Este é o método ideal quando tem um volume moderado de pedidos (até 10.000) e deseja simplificar o seu pipeline.

Agrupamento por Ficheiro vs. Agrupamento Inline

Antes de avançar para o código, vamos clarificar as diferenças entre as duas abordagens:

Critério Agrupamento por Ficheiro Agrupamento Inline
Volume máximo 1.000.000 de pedidos 10.000 pedidos
Pré-requisitos Carregar ficheiro JSONL Nenhum
Passos Carregar + Criar Tarefa Criar Tarefa (chamada única)
Casos de uso Produção, grandes volumes Testes, prototipagem, volumes médios

Criação de uma Tarefa Inline

Em vez de passar input_files, passa um parâmetro requests contendo a sua lista de pedidos diretamente:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Preparar pedidos inline
inline_requests = [
    {
        "custom_id": f"req-{i:04d}",
        "body": {
            "max_tokens": 150,
            "messages": [
                {
                    "role": "system",
                    "content": "You are a text classification expert."
                },
                {
                    "role": "user",
                    "content": f"Classify this text: {text}"
                }
            ]
        }
    }
    for i, text in enumerate(my_texts)
]

# Criar a tarefa com pedidos inline
job = client.batch.jobs.create(
    requests=inline_requests,
    model="mistral-small-latest",
    endpoint="/v1/chat/completions"
)

print(f"Inline job created: {job.id}")
print(f"Number of requests: {len(inline_requests)}")

A diferença no código é mínima: requests= em vez de input_files=. O restante fluxo de trabalho (monitorização do estado, descarga de resultados) é idêntico.

Exemplo Prático: Classificação de Tickets

Eis um exemplo completo de classificação de tickets de apoio ao cliente:

from mistralai.client import Mistral
import json
import time

client = Mistral(api_key="your-api-key")

# Simular tickets de apoio
tickets = [
    {"id": "TK-001", "message": "I cannot log in to my account"},
    {"id": "TK-002", "message": "How do I cancel my subscription?"},
    {"id": "TK-003", "message": "The app crashes on startup"},
    {"id": "TK-004", "message": "Can you add dark mode?"},
    {"id": "TK-005", "message": "My invoice is incorrect"},
]

# Construir pedidos inline
requests = [
    {
        "custom_id": ticket["id"],
        "body": {
            "max_tokens": 50,
            "messages": [
                {
                    "role": "system",
                    "content": (
                        "Classify the ticket into one of these categories: "
                        "AUTHENTICATION, BILLING, BUG, "
                        "FEATURE, SUBSCRIPTION. "
                        "Reply with the category only."
                    )
                },
                {"role": "user", "content": ticket["message"]}
            ]
        }
    }
    for ticket in tickets
]

# Lançar o lote inline
job = client.batch.jobs.create(
    requests=requests,
    model="mistral-small-latest",
    endpoint="/v1/chat/completions"
)

# Aguardar e recuperar resultados
while True:
    status = client.batch.jobs.get(job_id=job.id)
    if status.status in ("SUCCESS", "FAILED", "CANCELLED"):
        break
    time.sleep(5)

# Analisar resultados
if status.status == "SUCCESS":
    data = client.files.download(file_id=status.output_file)
    for line in data.read().decode("utf-8").strip().split("\n"):
        entry = json.loads(line)
        ticket_id = entry["custom_id"]
        category = entry["response"]["body"]["choices"][0]["message"]["content"]
        print(f"{ticket_id} -> {category.strip()}")

Quando Escolher Cada Abordagem

O fator decisivo não é apenas o volume, mas sim onde o agrupamento se encaixa no seu fluxo de trabalho. Durante a prototipagem, testa um prompt em algumas centenas de exemplos, refina-o e volta a executar. Escrever um ficheiro JSONL intermédio em cada iteração apenas desacelera o ciclo. O agrupamento inline remove este atrito: o seu script gera pedidos em tempo real, submete-os na mesma chamada e itera em minutos. A mesma lógica aplica-se a integrações leves, scripts de análise pontuais ou processamentos diários que se mantenham abaixo dos 10.000 pedidos.

O agrupamento por ficheiro assume a liderança assim que o lote se torna um elo de produção. Primeiro, mecanicamente: além de 10.000 pedidos, é a única opção. Mas, mais importante, estruturalmente: um ficheiro carregado é um artefacto duradouro. Pode reutilizá-lo para múltiplas tarefas, mantê-lo como registo exato do que foi submetido e separar claramente a etapa de preparação (que constrói, valida e versiona o ficheiro) da etapa de execução (que lança a tarefa). Quando uma tarefa em lote corre nightly sobre dados de clientes, esta rastreabilidade não é um luxo; é o que lhe permite responder à pergunta «O que enviámos ao modelo a 12 de março?» seis meses depois.

Na prática, muitas equipas utilizam ambos: inline durante o desenvolvimento do prompt, mudando depois para agrupamento por ficheiro ao industrializar. Como o código para monitorizar e recuperar resultados permanece idêntico, a migração limita-se a substituir requests= por input_files=.

Pontos-chave

  • O agrupamento inline remove a etapa de carregamento ao passar os pedidos diretamente através do parâmetro requests
  • Limite de 10.000 pedidos por tarefa inline, contra 1 milhão no agrupamento por ficheiro
  • A monitorização do estado e a descarga de resultados são idênticas em ambos os modos
  • Prefira o inline para prototipagem e volumes moderados; utilize o agrupamento por ficheiro para produção em larga escala