Product Search via Qdrant (padrão em produção)¶
Busca de produtos (experiências, guias, transfers, tickets) usando Qdrant como vector store. É a busca padrão em produção e em stage (
ENABLE_QDRANT_PRODUCT_SEARCH=truenos doiscloudbuild*.yaml). A busca via BigQuery (Busca de Produtos — BigQuery) continua no código como alternativa, usada só quando a flag está desligada.
Status¶
| Produção / stage | Qdrant (busca_produtos_qdrant) — _ENABLE_QDRANT_PRODUCT_SEARCH: 'true' |
| Default no código | False em ifriend_agent/config/feature_flags.py — ambiente local sem a env var cai no BigQuery |
| Como a troca acontece | Nos agentes e no buscar_produtos_orcamento, a flag decide qual tool é importada como busca_produtos (ver Tool do agente) |
| Indexação | Cloud Run Job product-search-sync (runtime/workers/product_search_sync/), disparado pelo Cloud Scheduler |
| Collection | products (produção) / stage_products (stage) |
Para rodar localmente igual a produção: ENABLE_QDRANT_PRODUCT_SEARCH=true + QDRANT_URL/QDRANT_API_KEY
(e ENVIRONMENT=stage para usar a collection de stage).
Visão Geral¶
Por que saiu do BigQuery: a tool busca_produtos (ifriend_agent/tools/busca_produtos_tool.py)
roda, a cada chamada do agente, uma query no BigQuery que: (1) gera o embedding da query via
ML.GENERATE_EMBEDDING (modelo mte002, 768D, Vertex AI); (2) faz um full scan em
mv_product_search_flat_embeddings calculando ML.DISTANCE (COSINE) contra 4 colunas de embedding
(title, description, location, features, pesos 0.40/0.30/0.20/0.10); e (3), quando há destino,
roda uma segunda passada de embedding + ML.DISTANCE para inferir o país mais provável e aplicar um
filtro geográfico (threshold 0.30). Isso custa 2 chamadas de embedding + 1-2 full scans por busca, sem
índice vetorial de fato.
A busca via Qdrant (o mesmo Qdrant da Knowledge Base) tem um pipeline de indexação próprio, gera o embedding da query localmente e não depende do BigQuery.
Fonte (CloudSQL MySQL, view de produtos)
│
▼
Cloud Run Job (Cloud Scheduler dispara periodicamente)
│ 1. lê produtos novos/alterados (watermark por updated_at)
│ 2. gera embeddings localmente (fastembed, paraphrase-multilingual-MiniLM-L12-v2, 384D)
│ 3. upsert no Qdrant (collection "products")
▼
Qdrant (qdrant-aiagent-service)
│
▼
Tool do agente (busca_produtos_qdrant, exposta como "busca_produtos")
│ 1. embedda a query do usuário localmente (mesmo modelo)
│ 2. filtro payload (tipo, idioma, geo exato, negócio) + busca vetorial nomeada
│ 3. reaproveita enrich_products.py + blocks/*.py já existentes
▼
Resposta ao agente (mesmo formato de busca_produtos)
1. Diagnóstico do Schema (BigQuery mv_product_search_flat_embeddings e a view-fonte real no MySQL)¶
O primeiro diagnóstico deste documento foi feito em cima do schema do BigQuery (a tabela já com
embeddings). Como a fonte real do novo pipeline é a view mv_product_search_flat no CloudSQL
(MySQL 5.7) — o dado antes de qualquer embedding — vale registrar o schema real dela, que revela
campos que a análise inicial não conhecia:
CREATE TABLE `mv_product_search_flat` (
`product_id` bigint(20) unsigned NOT NULL,
`source_type` enum('ifriend','experience') NOT NULL,
`product_type` varchar(30),
`title` varchar(255), `description` longtext,
`city` varchar(100), `state` varchar(100), `country` varchar(100), `country_code` varchar(3),
`latitude` decimal(14,8), `longitude` decimal(14,8),
`place_names` text, `interests` text, `languages` text,
`highlights` text, `includes` text, `excludes` text,
`variations` text, `provider_skus` text,
`duration` varchar(15), `price` decimal(14,2), `currency_code` varchar(4),
`rating` decimal(3,2), `review_count` int(11), `with_presential_guide` tinyint(1),
`published` tinyint(1), `salable` varchar(30), `featured` tinyint(1), `is_green` tinyint(1),
`doc_text` longtext,
`canonical_url` varchar(255), `display_url` tinytext, `updated_at` datetime,
`pro` tinyint(4), `price_net` decimal(14,2), `deleted_at` datetime, `agency_id` bigint(20) unsigned,
`photo_url` varchar(255), `needs_confirmation` tinyint(4), `confirmation_by` varchar(30),
PRIMARY KEY (`product_id`,`source_type`),
KEY `idx_place` (`country_code`,`state`,`city`),
KEY `idx_price` (`price`),
KEY `idx_flags` (`published`,`featured`,`is_green`),
FULLTEXT KEY `ft_semantic` (`title`,`description`,`doc_text`)
)
Achado crítico: a chave primária é composta (product_id, source_type). product_id sozinho
não é único — a mesma view combina duas tabelas de origem diferentes (ifriend e experience,
cada uma com seu próprio autoincrement), então um guia (source_type='ifriend') e uma experiência
(source_type='experience') podem ter o mesmo product_id. Isso é tratado em detalhe na seção 3
(design do Point ID do Qdrant) — é um cuidado que a análise inicial deste documento (feita só sobre o
schema pós-embedding do BigQuery, que não expõe source_type na tool atual) não tinha capturado.
O que já é uma boa base¶
| Característica | Por quê ajuda |
|---|---|
Conteúdo já particionado em fatias semânticas (title, description, location, features) |
Base pronta para vetores nomeados no Qdrant — evita "um vetor genérico que dilui sinal" |
Campos de filtro de negócio já existem (published, salable, deleted_at, needs_confirmation, pro, product_type, agency_id, price/price_net, currency_code, rating, review_count, featured, is_green) |
Baratos de indexar como payload filtrável, sem precisar de embedding para isso |
updated_at presente |
Permite sync incremental determinístico (watermark) |
latitude/longitude já existem na view |
Diferente do que o diagnóstico inicial assumia (geo só por texto livre) — isso permite filtro geográfico exato por distância real, não só aproximação por embedding (ver seção 3, revisado) |
interests já existe (texto livre) |
Já é, em essência, o campo de "tags/categoria" que a análise inicial recomendava criar do zero — precisa só ser normalizado (ver lacunas) |
languages já existe (texto livre) |
Idem — o dado já existe na origem, só não chega estruturado até guide_cards.py hoje |
doc_text (concatenação usada no índice FULLTEXT ft_semantic do MySQL) |
Já é um texto único title+description+extra pronto para uso — interessante como insumo futuro de busca híbrida (BM25 já existe no MySQL, dense no Qdrant) |
place_names, excludes, variations, provider_skus, with_presential_guide, confirmation_by |
Campos adicionais disponíveis na origem, não usados hoje pela tool BigQuery — candidatos a payload conforme necessidade |
Lacunas que reduzem precisão hoje¶
| Lacuna | Impacto | Recomendação |
|---|---|---|
interests/languages existem mas como texto livre não normalizado (não array) |
Não dá pra indexar como payload keyword diretamente — precisa de parsing/normalização no job de sync | Job de sync faz o split/normalize (ex.: "espanhol, inglês" → ["es","en"]) antes de gravar no payload |
duration é string livre |
Não é possível filtrar "passeios de até 3 horas" | Normalizar para duration_minutes (int) no job de sync |
| Sem sinal de popularidade/conversão (cliques, bookings, CTR) | Ranking não aprende com comportamento real — já listado como roadmap em docs/search/PRODUCT_SEARCH.md |
Reservar um campo numérico no payload do Qdrant para boost de score quando o dado existir |
product_id sozinho não é chave única (ver achado crítico acima) |
Risco de colisão de Point ID no Qdrant se não tratado explicitamente | Ver seção 3 — Point ID derivado de (source_type, product_id) |
product_type_embedding (no BigQuery) é computado mas não é usado no ranking atual (confirmado em busca_produtos_tool.py) |
Custo de embedding pago à toa | Não replicar esse vetor no Qdrant — product_type é enum fechado, resolve-se com payload filter |
Conclusão: o dado de origem é mais rico do que o diagnóstico inicial (feito só sobre o schema
pós-embedding do BigQuery) sugeria — interests, languages, latitude/longitude e doc_text já
existem na view MySQL. O trabalho do job de sync é menos "inventar campo novo" e mais "normalizar o que
já existe" para virar payload filtrável, além de resolver corretamente a chave composta.
2. Estratégia de Embeddings¶
Modelo¶
Atualização (deploy em stage): intfloat/multilingual-e5-small foi removido do catálogo de modelos
suportados pelo fastembed numa versão mais recente da lib (fastembed>=0.3.0, sem pin, resolveu para
0.8.0 no build e o job passou a falhar com Model ... is not supported in TextEmbedding). O modelo
usado agora é sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 — mesma dimensão (384D),
mesmo racional de escolha (leve, multilíngue, ~50 idiomas incl. PT/EN/ES), e suportado na versão
atual. Diferente do e5-small, não precisa de prefixos "query: "/"passage: ". fastembed foi fixado
em ==0.8.0 em runtime/workers/product_search_sync/requirements.txt para evitar repetir esse tipo de
quebra numa rebuild futura. A Knowledge Base também migrou para o mesmo modelo (KB_EMBEDDING_MODEL
default paraphrase-multilingual-MiniLM-L12-v2, fastembed==0.8.0 em ifriend_agent/requirements.txt),
e o Dockerfile pré-baixa esse modelo em FASTEMBED_CACHE_DIR — o mesmo cache serve às duas features.
Texto original desta seção (mantido como histórico da decisão de dimensão/latência, hoje com o modelo trocado por indisponibilidade, não por preferência):
Local via fastembed — mesmo modelo já em produção na
Knowledge Base: intfloat/multilingual-e5-small, 384D
(runtime/workers/knowledge_base/embedder.py, ifriend_agent/tools/knowledge_base_tool.py).
Decisão revista: a versão inicial deste documento propunha multilingual-e5-base (768D) só para
manter paridade dimensional com o BigQuery/mte002. Essa paridade era conveniência, não requisito
funcional (os dois pipelines de embedding já são independentes — ver nota abaixo). Diante da prioridade
de reduzir latência percebida pelo usuário (reclamações já existentes sobre demora do agente), a escolha
final é e5-small:
| Critério | e5-small (384D) |
e5-base (768D) |
|---|---|---|
| Parâmetros / custo de inferência | Menor — melhor latência por query | ~3x mais parâmetros |
| Qualidade em PT/EN/ES | A família E5 multilíngue é treinada no mesmo corpus para os dois tamanhos; o gap de qualidade entre small e base é mais visível em idiomas de poucos recursos. PT/EN/ES são idiomas de alto recurso, então a perda de qualidade esperada é pequena |
Levemente melhor, mas ganho marginal para esses 3 idiomas |
| Reuso de infraestrutura | Mesmo modelo da Knowledge Base — pode compartilhar a mesma instância singleton do modelo em memória entre as duas features, economizando RAM | Modelo adicional carregado em memória |
| Paridade dimensional com BigQuery | Não | Sim (mas não é usada por nada hoje) |
Se uma avaliação offline (comparando recall em uma amostra de queries reais contra os produtos esperados) mostrar que o modelo atual não atinge qualidade suficiente, o upgrade para um modelo maior (768D/1024D) fica documentado como opção — a collection pode ser reindexada com outro modelo/dimensão sem impactar a Knowledge Base, já que são coleções independentes.
Knowledge Base: fastembed foi fixado em ==0.8.0 e o modelo trocado para
paraphrase-multilingual-MiniLM-L12-v2 também em ifriend_agent/requirements.txt e
runtime/workers/knowledge_base/requirements.txt. Collections de afiliado indexadas com o modelo antigo
precisam ser reindexadas — ver docs/affiliate/knowledge-base.md.
Importante: os embeddings do Qdrant não são os mesmos hoje armazenados no BigQuery (aqueles vêm
de mte002/Vertex AI). Trata-se de um pipeline de embedding paralelo e independente, gerado a partir dos
dados crus do CloudSQL. As duas tools convivem com fontes de vetor diferentes — os scores de uma não são
comparáveis com os da outra, e isso deve ficar explícito para qualquer pessoa que for comparar as duas
buscas.
Campos embeddados¶
Mesmo particionamento que já funciona bem no BigQuery, mapeado a partir do texto bruto do MySQL:
| Vetor nomeado | Conteúdo de origem |
|---|---|
title |
title |
description |
description |
location |
concat de city + state + country |
features |
concat de highlights + includes |
product_type não é embeddado (ver seção 1) — vira payload filtrável.
3. Design da Collection no Qdrant¶
Segue o padrão já em produção em runtime/workers/knowledge_base/qdrant_writer.py (VectorParams,
Distance.COSINE, client.collection_exists/create_collection idempotente), mas com uma collection
única e global — produtos são um catálogo compartilhado entre afiliados; a diferenciação por afiliado
continua no pós-processamento, como hoje em context_product_price/context_product_affiliate_url.
Configuração¶
| Item | Valor |
|---|---|
| Nome da collection | products (stage_products em stage — mesmo padrão de prefixo de qdrant_ops.py/qdrant_writer.py) |
| Vetores nomeados | title, description, location, features — todos 384D (paraphrase-multilingual-MiniLM-L12-v2), Distance.COSINE |
| Point ID | derivado de (source_type, product_id) — ver subseção dedicada abaixo |
Point ID: por que product_id sozinho não serve¶
A view MySQL tem chave primária composta (product_id, source_type) — a mesma tabela combina produtos
de duas origens (ifriend e experience), cada uma com seu próprio autoincrement. Isso significa que
pode existir um guia e uma experiência com o mesmo product_id. Usar product_id puro como Point ID
no Qdrant causaria colisão silenciosa: o upsert do segundo produto sobrescreveria o do primeiro.
Solução: gerar o Point ID como um UUID determinístico a partir da chave composta, usando
uuid.uuid5 (Qdrant aceita string UUID como ID de ponto nativamente):
import uuid
NAMESPACE = uuid.UUID("...") # UUID fixo do projeto, gerado uma vez e versionado
def point_id(source_type: str, product_id: int) -> str:
return str(uuid.uuid5(NAMESPACE, f"{source_type}:{product_id}"))
Determinístico (mesmo input → mesmo UUID sempre) e sem colisão entre ifriend:123 e experience:123 —
mantém a idempotência de upsert que product_id puro daria, sem o risco de colisão. product_id e
source_type continuam guardados como campos separados no payload (abaixo), para filtro e para a
tool devolver a chave composta correta ao restante do pipeline (enrich_products.py e os block builders
precisam saber diferenciar as duas origens ao montar URLs/preços — checar na implementação se esse
código já assume product_id único; se sim, é um ajuste necessário para aceitar a chave composta,
independente deste pipeline Qdrant).
Payload¶
product_id, source_type, product_type, title, description,
city, state, country, country_code, latitude, longitude,
duration_minutes, price, price_net, currency_code,
rating, review_count,
published, salable, featured, is_green, pro, needs_confirmation,
canonical_url, display_url, photo_url, agency_id, updated_at,
interests, languages
interests/languages entram já normalizados como arrays (split + trim do texto livre da view — ver
seção 1) — não são campos novos a criar na origem, só precisam de parsing no job de sync.
Índices de payload (create_payload_index)¶
| Campo | Tipo de índice | Uso |
|---|---|---|
product_type |
keyword | filtro por tipo (guia/experience/ticket/transfer) |
source_type |
keyword | desambiguação ifriend vs experience |
country_code |
keyword | filtro geográfico exato |
city |
keyword | filtro geográfico exato |
pro |
bool | filtro de guia profissional |
published, salable |
bool/keyword | defesa extra além da exclusão no índice |
price |
range (float) | filtro de faixa de preço |
rating |
range (float) | filtro de nota mínima |
interests |
keyword (array) | filtro por categoria/interesse |
languages |
keyword (array) | filtro de idioma do guia |
location_geo (construído de latitude/longitude) |
geo (geo_point) |
filtro geográfico por raio real, ver abaixo |
Filtro geográfico: coordenadas reais > texto exato > vetor fuzzy¶
A view MySQL já tem latitude/longitude por produto — isso muda o desenho em relação ao BigQuery
(que só tem texto livre e por isso precisa de embedding fuzzy + threshold heurístico 0.30, documentado
em docs/search/PRODUCT_SEARCH.md). O design prevê três camadas, da mais precisa para a mais aproximada.
Implementado hoje: camadas 2 e 3. A camada 1 (geo por raio) ficou para uma v2. Na camada 3, a implementação refaz a busca sem o filtro geográfico; o vetor
location(peso 0.20 na combinação) é o que puxa os produtos do destino para cima — não há uma busca separada só pelo vetorlocation. Ver Fluxo.
- (não implementada) Filtro geo nativo do Qdrant (
geo_radius/geo_bounding_boxsobrelocation_geo) quando o destino informado puder ser geocodificado em coordenadas (ex.: via um dicionário canônico cidade→lat/long construído a partir dos próprios produtos já indexados, sem depender de serviço de geocoding externo) — é filtro por distância real, não por similaridade textual/semântica. - Filtro exato de payload (
city/country_code) quando o destino casar diretamente com o texto normalizado — rápido, sem geocoding. - Fallback por vetor
location(busca aproximada, equivalente ao comportamento atual do BigQuery) só quando as duas camadas acima não retornarem nada — cobre os casos multilíngues que hoje o embedding resolve bem (ex.: "Florence" → "Firenze").
Exclusão no índice, não filtro em runtime¶
Produtos com published=0, salable != 'online' ou deleted_at preenchido não entram no Qdrant —
o job de sincronização os remove/deixa de fora, em vez de aplicar filtro em toda busca (como o SQL faz
hoje). Isso reduz o tamanho da collection e o custo de cada busca.
4. Job de Sincronização (Cloud Run Job + Cloud Scheduler)¶
Segue o precedente de infraestrutura de runtime/workers/knowledge_base/, mas lendo do CloudSQL em vez
de reagir a eventos Pub/Sub.
Fonte¶
View mv_product_search_flat no CloudSQL (MySQL 5.7) — schema completo na seção 1. Contém todos os
campos de negócio necessários, sem colunas de embedding (essas nascem no próprio job, não na
origem), e com chave primária composta (product_id, source_type) — ver tratamento na seção 3.
Execução¶
Cloud Scheduler dispara o Cloud Run Job periodicamente (ex.: a cada 15–30 min, ajustável conforme volume de mudanças de catálogo).
Estratégia incremental e onde fica o watermark¶
Watermark por cursor composto (updated_at, product_id, source_type), no mesmo espírito do padrão já
usado em docs/bigquery-embedding/consulta-programada.sql (WHERE updated_at > @last_watermark), mas
com dois componentes extra para permitir checkpoint seguro por chunk (ver abaixo).
Decisão: persistir o watermark no próprio CloudSQL, em vez de Firestore — o job já mantém uma conexão com o MySQL para ler a view, então reaproveitar o mesmo banco para o estado de sincronização evita introduzir uma segunda dependência de infraestrutura só para isso. Tabela de controle dedicada (não a view, que é derivada e não deve receber escrita):
CREATE TABLE IF NOT EXISTS `qdrant_product_sync_watermark` (
`sync_name` varchar(50) NOT NULL PRIMARY KEY,
`last_synced_at` datetime NOT NULL,
`cursor_product_id` bigint unsigned NOT NULL DEFAULT 0,
`cursor_source_type` varchar(20) NOT NULL DEFAULT '',
`last_run_status` varchar(20) NOT NULL DEFAULT 'ok',
`updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB;
cursor_product_id/cursor_source_type foram adicionadas via ALTER TABLE guardado (idempotente,
ignora "coluna já existe") em watermark.py::ensure_table — mesmo padrão de migração de
ifriend_agent/memory/cloudsql/cloudsql_memory_service.py::_ensure_schema, já que a tabela já existia em
stage antes dessa mudança.
Por que um cursor composto, não só updated_at: um cursor baseado só em timestamp tem um problema
de "empate" — se dois produtos tiverem o mesmo updated_at e caírem em lados opostos de uma borda de
chunk, o segundo poderia ser pulado na retomada. A tupla (updated_at, product_id, source_type),
comparada via row-value comparison do MySQL (WHERE (updated_at, product_id, source_type) > (%s, %s,
%s)), bate exatamente com o ORDER BY da query — não há como pular ou reprocessar incorretamente uma
borda com empate.
Uma única linha (sync_name='product_search_qdrant'), já que é um único job. Fluxo:
- No início da execução, capturar
job_start_time = NOW()na aplicação (não no banco). SELECT last_synced_at, cursor_product_id, cursor_source_type FROM qdrant_product_sync_watermark WHERE sync_name = ... FOR UPDATE— o lock de linha protege o instante da leitura.- Consultar a view com o cursor composto (aceitável reprocessar produtos na borda — o upsert é idempotente pelo Point ID determinístico da seção 3, então isso é seguro e barato).
- Processar em chunks (ver próxima seção). A cada chunk processado com sucesso, gravar o cursor
como a tupla do último produto do chunk e fazer
COMMITimediatamente — cada chunk vira uma transação curta e durável, não uma só transação gigante presa até o fim do run inteiro. Isso libera o lockFOR UPDATEentre chunks (uma sobreposição rara de execuções do Scheduler vira redundância inofensiva graças ao upsert idempotente, não corrupção). - Só quando todos os chunks terminam com sucesso: fechar a janela, gravando o cursor sentinela
(job_start_time, 0, '')— usa o horário de início do job (não oMAX(updated_at)do lote lido) para não perder produtos escritos na origem durante o processamento, e inicia a próxima janela. - Se o job falhar/for morto no meio (timeout, OOM), o cursor fica exatamente onde o último chunk bem- sucedido deixou — a próxima execução retoma dali, não reprocessa o lote inteiro do zero.
Fluxo por execução¶
- Lê da view os produtos com cursor maior que o watermark (ou
updated_at IS NULL, vermysql_reader.py). - Normaliza campos de texto livre:
interests/languages(split em array),duration→duration_minutes(int), montalocation_geoa partir delatitude/longitude. - Processa em chunks de
SYNC_CHUNK_SIZE(200), na ordem original da query — cada chunk é separado em ativo/inativo internamente (não em duas listas globais, para o checkpoint refletir a posição real). - Para os ativos do chunk: gera os 4 embeddings localmente (fastembed, em sub-lotes de
EMBED_BATCH_SIZE), monta o payload completo (seção 3) e calcula o Point ID determinísticouuid5(source_type:product_id), fazupsertno Qdrant — idempotente, sem risco de colisão entreifriendeexperiencecom o mesmoproduct_id. - Para os inativos do chunk (
deleted_atpreenchido, oupublished=0/salable != 'online'): remove do Qdrant (client.deletepor Point ID, calculado da mesma chave composta). - Grava o checkpoint do chunk (passo 4 da seção anterior) e segue pro próximo chunk.
- Ao final de todos os chunks, fecha a janela (passo 5 da seção anterior).
Normalização necessária (não é dado novo, é parsing do que já existe)¶
Diferente da primeira versão deste documento — que assumia tags/languages/duration_minutes como
campos a serem criados do zero na origem — a view MySQL já expõe interests, languages e duration.
O trabalho do job é normalizar esses textos livres para os tipos que o Qdrant indexa bem (arrays de
keyword, inteiro em minutos). Isso é uma tarefa de implementação do próprio job, não uma dependência
externa de outro time.
Processamento em chunks (evita OOM numa primeira carga completa)¶
Uma primeira sincronização (view recém-populada, ou reindexação manual) pode enxergar o catálogo inteiro
como "alterado" de uma vez — todos os produtos ganham updated_at novo no momento da materialização.
Por isso product_processing.run() não acumula o catálogo inteiro em memória: fatia active_rows/
inactive_keys em lotes de SYNC_CHUNK_SIZE (200) e faz upsert/delete no Qdrant a cada lote, não
uma vez só no final. EMBED_BATCH_SIZE (32) continua controlando o sub-lote passado pro ONNX runtime
dentro de cada chunk — são dois níveis de lote independentes.
Limite conhecido, não resolvido: mysql_reader.fetch_changed_products ainda faz um único
fetchall() — se o catálogo for realmente enorme (dezenas/centenas de milhares de linhas com texto
longo), o rows bruto em memória antes do chunking ainda pode crescer bastante. Se o OOM voltar a
acontecer mesmo com o chunking, o próximo passo é paginar a própria leitura do MySQL (cursor não-
bufferizado ou keyset pagination em updated_at/product_id/source_type), não só o lado de escrita.
_TASK_TIMEOUT e retomada após timeout/kill: uma primeira carga completa pode legitimamente demorar
mais que o timeout padrão do Cloud Run Job — por isso _TASK_TIMEOUT está em 3600 (1h) nos dois
cloudbuild. Se mesmo assim o job for morto no meio (timeout, OOM, restart), o cursor composto fica
exatamente no último checkpoint de chunk salvo (ver seção acima) — a próxima execução retoma dali,
em vez de reprocessar o lote inteiro do zero. Isso resolve o desperdício de reembeddar tudo de novo a
cada tentativa; se o catálogo for grande o bastante para precisar de várias execuções mesmo com
retomada, considerar subir _TASK_TIMEOUT ainda mais (até o máximo suportado por Cloud Run Jobs, 24h).
5. Tool do Agente (busca_produtos_qdrant)¶
Arquivo: ifriend_agent/tools/busca_produtos_qdrant_tool.py. Mesma assinatura e mesmo formato de retorno
de busca_produtos (BigQuery), mais o parâmetro idioma — é um drop-in nos agentes.
Como os agentes escolhem a tool¶
Não há uma tool nova para o LLM: com a flag ligada, a função do Qdrant é importada com o nome
busca_produtos, então prompts e chamadas continuam iguais:
if get_flag("ENABLE_QDRANT_PRODUCT_SEARCH"):
from ifriend_agent.tools.busca_produtos_qdrant_tool import busca_produtos_qdrant as busca_produtos
busca_produtos.__name__ = "busca_produtos"
else:
from ifriend_agent.tools.busca_produtos_tool import busca_produtos
Esse bloco está em discovery_agent, itinerary_agent, support_agent, custom_tour_agent e em
buscar_produtos_orcamento_tool.py (usado por quote_agent, custom_tour_agent e proposal_agent).
A flag é lida no import: trocar o valor exige reiniciar o processo. Ao criar um agente/tool novo que
busque produtos, repita esse bloco em vez de importar busca_produtos_tool direto.
Assinatura¶
async def busca_produtos_qdrant(
tool_context: ToolContext,
metadados_busca: str,
destino: Optional[str] = None,
tipo_produto: Optional[str] = None,
guia_pro: Optional[bool] = False,
idioma: Optional[str] = None,
limit: Optional[int] = 10,
suppress_blocks: Optional[bool] = False,
) -> list[dict]:
| Parâmetro | Descrição |
|---|---|
metadados_busca |
Texto livre da busca (obrigatório; vazio → [{"erro": ...}]) |
destino |
Cidade, estado ou país. Filtro exato após normalização (sem acento, minúsculas) contra city_norm/country_norm; sem resultado, refaz sem o filtro geográfico |
tipo_produto |
"guia"/"ifriend"/"guide"/"virtual_guide" → product_type="guia"; "experience"/"ticket"/"transfer"/"package" → o próprio tipo. Se a query contém termos de marca ("local friend", "ifriend"...) com tipo guia, o filtro de tipo é removido |
guia_pro |
Com tipo guia, filtra pro=True |
idioma |
Só nesta tool. Idioma falado pelo guia, em português (ex: "japonês"), filtro exato em languages_norm. Nunca é relaxado: se nenhum guia fala o idioma, o resultado é vazio |
limit |
Máximo de produtos (padrão 10) |
suppress_blocks |
True → só a lista de produtos, sem blocks de UI |
Fluxo¶
- Embedda
metadados_buscalocalmente com fastembed (paraphrase-multilingual-MiniLM-L12-v2, 384D) — sem chamada de rede. O vetor fica em cache em memória porPRODUCT_SEARCH_CACHE_TTL. - Monta o
Filterdo Qdrant:needs_confirmation=Falsequando o afiliado não permite (affiliate_config.allowNeedsConfirmation), tipo de produto,proelanguages_norm. - Faz uma
query_pointspor vetor nomeado (title,description,location,features), em paralelo, com over-fetch demax(limit × 5, 50)pontos cada. - Combina por soma ponderada de distância (
1 - score) com os pesos herdados do BigQuery (title 0.40 / description 0.30 / location 0.20 / features 0.10); um ponto que não veio num vetor conta distância 1.0 nele. Ordena e corta emlimit.relevance = round((1 - distance) * 100, 2). - Com
destino: primeiro com o filtro exatocity_normOUcountry_norm; se vier vazio, repete sem o filtro geográfico. - Enriquece (
context_product_price,context_product_catalog_status,context_product_affiliate_url,context_product_whitelabel_url) e monta os blocks (experience_cards,guide_cards). - Devolve
product_idesource_typepor item (a chave composta da origem — ver seção 3).
Reuso direto de código existente (sem duplicar)¶
ifriend_agent/tools/context/enrich_products.py— preço, status de catálogo, URL de afiliado/whitelabel.ifriend_agent/tools/blocks/experience_cards.pyeguide_cards.py— geração dos blocks de UI.
Fallback progressivo¶
Mesma quantidade de tentativas do BigQuery, mas em ordem diferente: aqui o filtro geográfico é relaxado antes do tipo de produto (no BigQuery é o contrário). São no máximo 4 buscas:
1. com tipo_produto + destino exato
↓ (vazio)
2. com tipo_produto, sem filtro geográfico (só se havia destino)
↓ (vazio)
3. sem tipo_produto + destino exato (só se havia tipo_produto)
↓ (vazio)
4. sem tipo_produto, sem filtro geográfico
idioma e needs_confirmation nunca são relaxados.
Erros¶
Se o Qdrant falhar (rede, collection inexistente etc.), a tool devolve
[{"erro": "Erro ao consultar o vector store", "detalhe": "..."}] e loga um warning. Não há fallback
automático para o BigQuery — para voltar ao BigQuery, desligue ENABLE_QDRANT_PRODUCT_SEARCH e faça
um novo deploy.
6. Performance e Cold Start (embedding de query em tempo real)¶
A tool faz uma inferência de embedding local no caminho crítico de cada busca. O risco dominante não é o custo de inferência em si (texto curto, modelo já carregado — tipicamente poucos milissegundos), e sim carregar o modelo do zero na primeira requisição de um processo frio.
| Mitigação | Status |
|---|---|
| Modelo pré-baixado na imagem | ✅ O Dockerfile baixa o modelo em FASTEMBED_CACHE_DIR no build — em runtime não há download, só carga em memória. PRODUCT_EMBEDDING_MODEL precisa bater com o modelo pré-baixado, senão o cache não serve. |
| Cache de queries repetidas | ✅ _TTLCache em memória (mesmo padrão de knowledge_base_tool.py), chave por hash do modelo + query normalizada, TTL PRODUCT_SEARCH_CACHE_TTL. |
| Preload no startup | ⏳ Ainda não: o modelo é carregado de forma lazy na primeira busca de cada processo (_get_embedder()), que paga a carga do ONNX runtime + pesos. |
| Min-instances ≥ 1 | Recomendado para o serviço do agente, senão todo cold start paga essa carga de novo. |
| Modelo compartilhado com a Knowledge Base | Mesmo modelo nas duas features, mas cada tool mantém seu próprio singleton TextEmbedding em memória — unificar economizaria RAM. |
| Benchmark | ifriend_agent/scripts/benchmark_product_search.py compara BigQuery e Qdrant (latência e resultados). |
7. Convivência com o BigQuery e Próximos Passos¶
- Qdrant é o padrão em produção e stage. A tool do BigQuery continua no código e é usada quando
ENABLE_QDRANT_PRODUCT_SEARCHestá desligada (inclusive em ambiente local sem a env var, já que o default no código ainda éFalse). - Os scores das duas tools não são comparáveis (modelos de embedding diferentes).
- Pendências conhecidas: camada 1 do filtro geográfico (geo por raio), preload do modelo no startup, paginação da leitura do MySQL no job de sync (ver seção 4) e alinhar o default da flag no código com produção.
- Roadmap incremental (já listado em
docs/search/PRODUCT_SEARCH.md) e como o Qdrant facilita cada item:
| Item do roadmap | Como o Qdrant ajuda |
|---|---|
| Hybrid search (dense + BM25) | Qdrant suporta sparse vectors nativamente — pode ser adicionado como um vetor nomeado extra sem redesenhar a collection |
| Reranker (BGE-reranker-v2) | Retrieval em duas etapas: over-fetch no Qdrant, rerank em cima do top-N — natural de plugar na tool |
| Query rewriting via LLM | Independente do vector store, mas se beneficia da menor latência do Qdrant para iterar mais rápido |
| Fine-tuning de embeddings para turismo BR | A collection isolada permite trocar o modelo/dimensão dos vetores de produto sem impactar a Knowledge Base |
| Logs de feedback (cliques/conversão) | Vira payload numérico (popularity_score) usável em boost de score nas queries do Qdrant |
Variáveis de Ambiente¶
Tool de consulta (serviço do agente):
| Variável | Default | Descrição |
|---|---|---|
ENABLE_QDRANT_PRODUCT_SEARCH |
false no código, true em produção e stage |
Usa o Qdrant em vez do BigQuery na busca de produtos |
QDRANT_URL / QDRANT_API_KEY |
— (secrets trip-ifriend-qdrant-url / trip-ifriend-qdrant-apikey) |
Mesma instância Qdrant da Knowledge Base |
PRODUCT_SEARCH_COLLECTION |
products |
Nome da collection (prefixo stage_ quando ENVIRONMENT=stage) |
ENVIRONMENT |
production |
stage → collection stage_products — precisa bater com o job de sync |
PRODUCT_EMBEDDING_MODEL |
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 |
Modelo fastembed (384D) — precisa ser idêntico ao do job de sync e ao pré-baixado no Dockerfile |
PRODUCT_SEARCH_TOP_K |
10 |
Limite padrão de resultados |
PRODUCT_SEARCH_CACHE_TTL |
600 |
TTL (segundos) do cache em memória de embeddings de query |
FASTEMBED_CACHE_DIR |
/app/.fastembed_cache (no Dockerfile) |
Onde o modelo pré-baixado fica na imagem |
As variáveis do job de sync (usuário MySQL dedicado etc.) estão em
Variáveis de Ambiente → Search. O tamanho dos lotes
(SYNC_CHUNK_SIZE=200, EMBED_BATCH_SIZE=32) e o nome da tabela de watermark são constantes no código,
não variáveis de ambiente.
Arquivos Envolvidos (referência)¶
| Arquivo | Papel |
|---|---|
ifriend_agent/tools/busca_produtos_qdrant_tool.py |
Tool de consulta (Qdrant) — padrão em produção |
ifriend_agent/tools/busca_produtos_tool.py |
Tool BigQuery — usada só com a flag desligada |
ifriend_agent/tools/buscar_produtos_orcamento_tool.py |
Wrapper multi-interesse — escolhe a tool pela mesma flag |
runtime/workers/product_search_sync/ |
Job de sincronização CloudSQL → Qdrant |
cloudbuild-product-search-sync.yaml / .stage.yaml |
Build e deploy do job de sync |
ifriend_agent/scripts/benchmark_product_search.py |
Benchmark BigQuery × Qdrant |
docs/search/PRODUCT_SEARCH.md |
Tool BigQuery — referência de pesos, wrapper multi-interesse e roadmap |
runtime/workers/knowledge_base/qdrant_writer.py |
Precedente de escrita/upsert no Qdrant a seguir |
runtime/workers/knowledge_base/embedder.py |
Precedente de uso de fastembed como singleton |
ifriend_agent/tools/knowledge_base_tool.py |
Precedente de busca async no Qdrant com cache TTL e threshold |
ifriend_agent/tools/context/enrich_products.py |
Enriquecimento pós-query — reaproveitado sem alteração |
ifriend_agent/tools/blocks/experience_cards.py, guide_cards.py |
Geração de blocks de UI — reaproveitados sem alteração |
runtime/infra/k8s/qdrant.yaml |
Deployment do Qdrant (qdrant-aiagent-service) |