O recurso de pesquisa de produtos está no modo de manutenção. Para aumentar a escalabilidade e ter a mesma funcionalidade da Pesquisa de produtos, use o Armazenamento do Vision.
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Nesta página, você verá etapas de solução de problemas que podem ser úteis se tiver
problemas ao usar a Pesquisa de produtos da API Vision.
Resultados da pesquisa
Qual é o número máximo de resultados retornados?
O número máximo de resultados retornados varia de acordo com a consulta devido aos detalhes
de implementação. O valor máximo garantido dos resultados retornados é 500. Se forem solicitados mais,
o número solicitado poderá não ser atendido.
É possível definir um limite de pontuação para os resultados?
As pontuações dos resultados da pesquisa não são calibradas. Isso significa que as pontuações dos resultados para uma determinada
consulta serão comparáveis (é assim que os resultados são classificados). No entanto, as pontuações dos resultados da
consulta A e da consulta B não são necessariamente comparáveis. Isso significa que não há um limite
fixo adequado para um determinado caso de uso.
É possível definir um limite com base nas suas próprias experiências. Se você quiser definir um
limite, defina-o com base no rótulo de cada item. Isso significa que
você precisa definir um limite de pontuação de resultados para "Sapatos" separadamente de "Bolsas" etc.
para cada rótulo.
Há uma maneira de saber por que um determinado resultado foi classificado melhor do que outro?
Atualmente, a Pesquisa de produtos da API Vision não oferece suporte a recursos que explicam
o motivo pelo qual um determinado resultado foi retornado.
Qual é a diferença entre usar productGroupedResults e
o recurso Localizador de objetos da API Vision?
A resposta productGroupedResults retornará uma lista de itens detectados,
os respectivos rótulos e pontuações previstos, as caixas delimitadoras e uma lista de classificação dos resultados
da pesquisa de produtos para cada item. Essa resposta equivale a enviar primeiro a imagem da consulta ao
recurso Localizador de objeto da API Vision e, em seguida, enviar a imagem com cada
caixa delimitadora do item de produto (filtrada com os rótulos relevantes) à Pesquisa de produtos da API Vision.
Uma vantagem de usar productGroupedResults é que ele é mais rápido
e direto porque faz apenas uma chamada de API. No entanto, se houver alguma
lógica de aplicativo personalizada que precise ser implementada entre a detecção de objeto e
a consulta de pesquisa, um método de duas etapas será uma boa abordagem. Um exemplo desse caso
seria adicionar filtros da Pesquisa de produtos da API Vision com base em rótulos
de objetos.
Se eu souber o local de um produto em uma imagem, preciso cortá-la antes de consultar
a API com ela?
Essa situação pode ocorrer se, por exemplo, um usuário tiver permissão para desenhar uma caixa delimitadora em torno
do item que quiser pesquisar. Em geral, não corte a
imagem antes de enviá-la para a API. O motivo é que nossa API usará a caixa delimitadora
da consulta para retornar resultados segmentados, bem como o contexto geral da imagem, que
costuma ser útil para melhorar os resultados.
Imagens de referência
O que são boas imagens de referência do produto?
Boas imagens de referência mostram claramente o produto e não exibem outros
objetos. Um bom exemplo são as imagens tipo
packshot (em inglês). Elas são usadas para mostrar ao usuário
um produto na página dele ou em anúncios e geralmente contam com um
fundo branco. Imagens do produto em outros ambientes também produzem boas imagens
de referência, desde que não apresentem outros produtos. Use todas as
imagens disponíveis como imagens de referência.
Qual é o tamanho ideal para imagens de referência e imagens que você usa para pesquisar produtos?
uma imagem ideal se concentra no produto e preenche a maior parte dela. Imagens
que contenham somente uma representação pequena ou pouco clara de um produto produzirão resultados menos
desejáveis. Consequentemente, o tamanho aparente do produto na imagem é mais importante do que o tamanho
específico. No entanto, como uma recomendação geral, use imagens com 600 pixels
ou mais no lado maior para imagens de referência e de pesquisa.
Qual é o número ideal de imagens de referência para um produto específico?
A API Vision da Pesquisa de Produtos funciona bem mesmo com apenas uma imagem de referência.
Normalmente, de três a oito imagens fornecem informações necessárias para gerar os resultados adequados na
Pesquisa de produtos da API Vision,
especialmente se elas tiverem algumas variações. Essas variações incluem diferentes
orientações do produto, iluminação ou plano de fundo.
Outras imagens de referência podem ser adicionadas ao índice e não costumam diminuir a acurácia
das informações do produto.
Como ter mais imagens de referência para meus produtos?
A melhor maneira de aprimorar a acurácia da Pesquisa de produtos API Vision é adicionar mais boas
imagens de referência para os produtos. Se você já tiver enviado um conjunto representativo de imagens
de produtos e ainda quiser aumentar a
acurácia de alguns produtos, poderá usar outras imagens existentes ou coletar
mais imagens para eles.
Se quiser usar outras imagens, elas precisam mostrar claramente o produto
e não podem ter outros objetos que desviem a atenção. Por exemplo, é possível ter fotos de uma
modelo usando uma determinada camisa combinando com uma calça. Essa imagem sozinha não seria uma
boa imagem de referência para a camisa. No entanto, se você inserir uma caixa delimitadora
ao redor da camisa ou cortar a imagem para incluir somente ela, será uma boa imagem
de referência. Use o recurso Localizador
de objetos da API Vision para inserir
caixas. Esse método pode ser usado como complemento ou substituição das anotações
de caixa delimitadora inseridas por humanos.
Adicionar aprimoramentos de dados ao meu conjunto de produtos afeta a acurácia da API?
A ideia de adicionar versões aprimoradas das imagens de referência existentes
(por exemplo, inversão esquerda-direita, contraste tremido etc.) é interessante, mas normalmente
afeta pouco a acurácia.
Gerenciamento de dados
Qual é a maneira recomendada de atualizar um conjunto de produtos em produção?
Atualize o conjunto com novos produtos à medida que
o inventário mudar. Se as mudanças forem pequenas,
adicione ou exclua produtos conforme necessário. Outra opção, se houver uma mudança significativa
no inventário ou nas imagens de referência, é criar um novo conjunto
de produtos com as mudanças e testar a qualidade da pesquisa antes de migrar totalmente para o novo conjunto.
Em qualquer um dos casos, acompanhe quais produtos e
imagens fazem parte do conjunto salvando o arquivo CSV de importação em lote para facilitar
a referência ou reversão.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-02 UTC."],[],[],null,["# General tips\n\nThis page describes troubleshooting steps that you might find helpful if you\nrun into problems using Vision API Product Search. \n\n### Search results\n\n#### What is the maximum number of results returned?\n\nThe maximum number of results returned will vary from query to query due to implementation\ndetails. The maximum guaranteed amount of results returned is 500. If more are requested,\nthe requested number may not be met.\n\n#### Can I set a score threshold for results?\n\nThe search result scores are not calibrated. This means that the result scores for a given\nquery will be comparable (this is how results are ranked). However, the result scores for\nquery A and query B are *not necessarily* comparable. This means there is no one fixed\nthreshold suitable for a given use case.\n\nIt is possible to set a threshold based on your own experiments. If you want to set a\nthreshold, you should set this threshold on a per item label basis. This means that\nyou should set a results score threshold for \"Shoes\" independently of \"Bags\", etc.\nfor each label.\n\n#### Is there a way to know why a particular result was ranked higher than another?\n\nCurrently the Vision API Product Search does not support any features that explain\nwhy a particular result was returned.\n\n#### What is the difference between using `productGroupedResults` and using\nthe Object Localizer feature of the Vision API?\n\nThe `productGroupedResults` response will return a list of detected items,\ntheir predicted label and score, their bounding boxes, and a ranked list of product\nsearch results for each item. This response is equivalent to first sending the query image to\nthe Object Localizer feature of the Vision API and then sending the image along with each\nproduct item bounding box (filtered to the relevant labels) to Vision API Product Search.\n\nOne benefit of using `productGroupedResults` is that it is faster\nand more direct because it only makes a single API call. However, if there is some\ncustom application logic that needs to be implemented between the object detection and\nthe search query then a two step method is a good approach. An example of such a case\nwould be adding Vision API Product Search filters based on object\nlabels.\n\n#### If I know the location of a product in an image should I crop the image before querying\nthe API with it?\n\nThis situation might arise if, for example, a user is allowed to draw a bounding box around\nthe item that they want to search. In general you should not crop the\nimage before sending it to the API. The reason is that our API will use both the query\nbounding box to return targeted results as well as the overall image context, which is\nfrequently helpful for improving the results.\n\n### Reference images\n\n#### What are good product reference images?\n\nGood reference images show the product clearly and do not have any other\nobjects in the image. A typical example of good reference images are\n[\"packshot\"](https://en.wikipedia.org/wiki/Packshot) images. These images are frequently used to show the user\na product on the product page or in advertising, and typically taken in front of a\nwhite background. Images of the product in other environments also make good reference\nimages provided there are not any other products in the image. You should use all such\nimages that are available for reference images.\n\n#### What is the ideal image size for reference images and images you use to search for products?\n\nAn ideal image focuses on the product, and the product fills the majority of the image ; images\ncontaining only a small or unclear representation of a product will produce less desirable\nresults. Consequently, the apparent size of the product in the image matters more than specific\nimage size. However, as a *general* recommendation, use images with 600 pixels\nor more on the largest side for reference and search images.\n\n#### What is the optimal number of reference images for a particular product?\n\nThe Vision API Product Search can work well even with only one reference image of a product.\nTypically 3 to 8 images provide necessary information to get proper results from the\nVision API Product Search,\nespecially if these images have some variations. Such variations include different\norientations of the product, different lighting, or a different background.\nAdditional reference images can be added to the index, and should not generally decrease\naccuracy.\n\n#### How can I get more reference images for my products?\n\nThe best way to improve the accuracy of Vision API Product Search is to add more good\nreference images for products. If you have already uploaded a representative set of product\nimages and you'd still like to increase the\naccuracy for some products you can use other existing images or collect\nmore images for those products.\n\nTo use other existing images make sure they clearly show the product\nand don't have other distracting objects. For example, you might have photos of a\nmodel wearing a particular shirt along with pants. This image *alone* wouldn't be a\ngood reference image for the shirt product. However, if you provide a bounding box\naround the shirt or crop the image to only include the shirt it would be a good reference\nimage. You can use the Vision API's [Object\nLocalizer](/vision/docs/object-localizer) feature to propose\nboxes. This method can be used alongside or instead of human-provided bounding box\nannotations.\n\n#### Would it help the accuracy of the API to add data augmentations to my product set?\n\nThe idea of adding augmented versions of existing reference images\n(for example, left-right flips, jittered contrast, etc.) is sensible, but typically does\nlittle to increase the accuracy.\n\n### Data management\n\n#### What is the recommended way to update a product set in production?\n\nUpdate your product set with new products as your\ninventory changes. If the changes are small you can\nadd or delete products as needed. Alternatively, if there is a significant change in your\ninventory or in your reference images you can create a new product\nset with the changes and test the search quality before fully switching over to the new set.\nIn either case, you should keep track of which products and\nimage are in your product set by saving your batch import CSV file for easy\nreference or rollback."]]
