Pular para o conteúdo principal

Importações assíncronas de datasets

Importe um arquivo CSV ou JSONL para um dataset em poucos passos: crie a importação, envie o arquivo, confira como as colunas são mapeadas e confirme. A confirmação enfileira a importação e retorna na hora; as linhas são adicionadas em segundo plano.

Limites e endpoints​

GET  /api/v1/projects/{owner_slug}/{project_slug}/datasets/limits
POST /api/v1/projects/{owner_slug}/{project_slug}/datasets/{dataset_id}/imports
PUT  /api/v1/projects/{owner_slug}/{project_slug}/imports/{import_id}/content
POST /api/v1/projects/{owner_slug}/{project_slug}/imports/{import_id}/profile
POST /api/v1/projects/{owner_slug}/{project_slug}/imports/{import_id}/preview
POST /api/v1/projects/{owner_slug}/{project_slug}/imports/{import_id}/confirm
GET  /api/v1/projects/{owner_slug}/{project_slug}/imports
GET  /api/v1/projects/{owner_slug}/{project_slug}/imports/{import_id}
POST /api/v1/projects/{owner_slug}/{project_slug}/imports/{import_id}/cancel

Leia /datasets/limits primeiro. Ele publica os limites de upload e do dataset, além da capacidade usada e restante. Datasets de chat informam exemplos, mensagens e bytes de texto. Datasets de embeddings informam exemplos e bytes de texto. O ID e o tipo exatos do dataset determinam a autorização; um ID desconhecido ou de outro projeto nunca seleciona o dataset padrão.

Fluxo​

  1. Crie a importação com filename e size_bytes opcionais.
  2. Envie o arquivo como o objeto upload da resposta descreve (method, url e headers). Quando upload.kind é backend, isso é um PUT dos bytes do arquivo para a rota /content da importação com sua chave de API.
  3. Chame /profile para obter cabeçalhos, amostras, tamanho exato em bytes, SHA-256 e um mapeamento sugerido.
  4. Chame /preview com o mapeamento e invalid_row_policy (fail ou skip). O preview mostra amostras, não uma validação completa do arquivo.
  5. Chame /confirm com o mesmo mapeamento e a mesma política, expected_sha256 e um idempotency_key estável. O digest vincula a confirmação ao arquivo analisado. A confirmação reserva a capacidade do dataset de que as linhas precisam e enfileira a importação.
  6. Consulte o detalhe até succeeded, failed ou cancelled.

O fluxo também usa os estados created, uploaded, profiling, ready_for_mapping, importing e purging. Uma importação de chat incompleta fica invisível na listagem e no treino; uma importação de embeddings prepara as linhas e só as publica após a promoção. O cancelamento libera a reserva. Linhas preparadas de importações com falha ou canceladas são removidas em lotes limitados.

Importações de embeddings​

Um dataset de embeddings aceita CSV ou JSONL UTF-8 (.jsonl/.ndjson, um objeto plano por linha). Informe um mapeamento explícito:

{"anchor":"consulta","positive":"passagem","negative":"negativo_dificil","metadata":["idioma"]}

anchor e positive são obrigatórios. negative e metadata são opcionais. Os valores JSONL mapeados devem ser strings. Uma chave JSON duplicada é recusada; um valor mapeado aninhado ou de outro tipo torna a linha inválida. Cada linha válida cria um novo par, reutiliza um par existente com o mesmo negativo ou é informada como conflito quando o negativo é diferente. A reutilização preserva o exemplo e registra outro vínculo com a linha de origem. O limite compartilhado de 512 MiB conta o texto e os metadados armazenados. A confirmação reserva os bytes exatos das linhas válidas mapeadas; a promoção liquida a reserva conforme as linhas realmente criadas.

Erros usam {"detail":{"code","message"}}. Falhas de capacidade têm códigos 409 tipados; um upload alterado retorna 409 import_object_changed. Uma importação concluída informa suas contagens e uma amostra limitada de motivos de erro.

A lista de importações retorna {data, next_cursor, total_count}, das mais recentes às mais antigas. Use limit (padrão 25, máximo 50) e envie next_cursor como cursor para a próxima página. O parâmetro opcional dataset_id filtra os registros e o total. Mantenha o mesmo filtro de dataset ao seguir um cursor.