Extração de características
Como a IA preenche as características dos produtos a partir de nome, descrição e fotos, e como revisar o que ela propõe.
Características (também chamadas de ficha técnica) são os atributos de um produto que o cliente usa para filtrar e comparar: cor, material, voltagem, capacidade. Preenchê-las à mão em um catálogo grande é lento. A extração de características pede à IA que leia o nome, a descrição e até 4 fotos de cada produto e preencha as características que a categoria do produto prevê.
A extração roda como um job em segundo plano. Para cada característica a IA informa um valor e uma confiança (de 0 a 1). A plataforma decide sozinha o que fazer com cada valor, conforme a confiança, e o que fica em dúvida vai para uma fila de revisão que você aprova ou recusa.
Como funciona
- Configure a ficha técnica da categoria
Na administração da loja, associe à categoria as características que ela deve ter. Sem isso a extração é recusada com
422. - Crie o job
Chame Jobs de extração com a categoria (todos os produtos dela) ou com uma lista de produtos.
- Acompanhe
Consulte o job até o status ser
done. O ritmo é de cerca de 1 produto a cada 2 segundos ou mais. - Revise
Liste a fila de revisão e aprove ou recuse os itens.
O que acontece com cada valor
| Confiança | Situação | Resultado |
|---|---|---|
| < 0,5 | Qualquer. | Descartado. Nada é guardado. |
| >= 0,5 | O produto já tem valor nessa característica. | Ignorado (skipped). Não aparece na revisão. |
| 0,5 a 0,8 | Produto sem valor. | Vai para a fila de revisão (review). |
| >= 0,8 | Característica livre (texto, número, data, sim/não), ou de lista cuja opção já existe. | Gravado direto (applied). |
| >= 0,8 | Característica de lista (cor, marca, autor, seleção) e a opção ainda não existe. | Vai para a fila de revisão. |
Status do job
| Status | Significado |
|---|---|
queued | Criado, ainda não começou. |
running | Processando os produtos, um a um. |
done | Todos os produtos foram processados. Não quer dizer que algo foi preenchido: confira applied e review. |
cancelled | Você cancelou. Valores já gravados permanecem. |
Conceitos-chave
Ficha técnica da categoria
É a lista de características associadas a uma categoria. A IA só procura os atributos dessa lista, e para um produto usa a ficha da categoria dele (ou das categorias acima, quando herdada). O cadastro da ficha fica fora desta seção, na administração de categorias.
Confiança
Número de 0 a 1 que a IA dá a cada valor. A fila de revisão vem ordenada da maior para a menor confiança, então os itens mais seguros aparecem primeiro.
Identificadores
Job, produto, característica e item de revisão são UUID em string.
Endpoints
| Método | Caminho | Para que serve | Auth |
|---|---|---|---|
| POST | /api/v1/admin/feature-extraction/jobs | Criar job | admin |
| GET | /api/v1/admin/feature-extraction/jobs/{id} | Consultar job | admin |
| POST | /api/v1/admin/feature-extraction/jobs/{id}/cancel | Cancelar job | admin |
| GET | /api/v1/admin/feature-extraction/review | Listar a fila de revisão | admin |
| POST | /api/v1/admin/feature-extraction/review/apply | Aprovar itens | admin |
| POST | /api/v1/admin/feature-extraction/review/reject | Recusar itens | admin |
Erros comuns
- Criar o job para uma categoria sem ficha técnica. Dá
422com a orientação de configurar a ficha antes. - Achar que
donesignifica sucesso. Se a IA falhar em um produto, o job segue e terminadonecomappliedereviewem zero. Sempre confira os contadores. - Esperar que valores existentes sejam atualizados. A extração só preenche o que está vazio.
- Aprovar itens com ids de outro job ou já decididos. O servidor os ignora em silêncio e responde
200. - Criar dois jobs sobre os mesmos produtos ao mesmo tempo. Cada um gasta IA e eles disputam as mesmas características.
- Chamar sem o privilégio
manage_catalog. Dá403.