Acelerar o desempenho das consultas com funções de IA

A aceleração da função de IA permite otimizar o desempenho ao executar consultas que usam funções de IA. Ela oferece o mesmo desempenho ou um desempenho melhor do que as funções baseadas em matrizes, sem exigir que você escreva consultas complexas. Para mais informações sobre as funções de IA, consulte Visão geral das funções de IA.

A aceleração da função de IA oferece suporte às seguintes funções de IA:

  • ai.if: a aceleração se aplica apenas a consultas SELECT em que a função está na cláusula WHERE. Ela oferece suporte a uma única função ai.if por verificação e funciona com verificação sequencial, de índice e de heap de bitmap. Se uma consulta contiver várias verificações de tabela, por exemplo, em tabelas, relações ou expressões de tabela comuns (CTEs, na sigla em inglês) diferentes, você poderá acelerar uma função ai.if por verificação.
  • ai.rank: a aceleração se aplica apenas a consultas SELECT em que a função está na cláusula ORDER BY. Ela oferece suporte a uma única função ai.rank por verificação. Se uma consulta contiver várias verificações de tabela, por exemplo, em tabelas, relações ou CTEs diferentes, você poderá acelerar uma função ai.rank por verificação.

Ativar a aceleração da função de IA

Para ativar a aceleração da função de IA, defina a google_ml_integration.enable_ai_function_acceleration flag como on. Essa flag fica desativada por padrão e controla se o executor de consultas pode descarregar operações de IA qualificadas para o nó de aplicação da função de IA para aceleração. Quando não definida ou definida como off, todas as operações de consulta são executadas pelo executor padrão do PostgreSQL.

É possível configurar essa flag no nível da sessão ou da instância.

Para ativar a aceleração da função de IA no nível da instância, use o gcloud alloydb instances update comando:

gcloud alloydb instances update INSTANCE_ID \
  --database-flags google_ml_integration.enable_ai_function_acceleration=on \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --project=PROJECT_ID

Substitua:

  • INSTANCE_ID: o ID da instância que você quer atualizar.
  • REGION_ID: o ID da região em que o cluster está localizado. Para mais informações, consulte Regiões com suporte.
  • CLUSTER_ID: o ID do cluster.
  • PROJECT_ID: o ID do projeto.

Para mais informações sobre como definir uma flag no nível da instância, consulte Configurar flags do banco de dados.

Verificar a aceleração da função de IA

Para verificar se a aceleração da função de IA está ativada, use a instrução EXPLAIN para analisar a consulta.

Verificar a aceleração da função de IA para consultas ai.if

O exemplo a seguir mostra como ativar a aceleração da função de IA para a sessão atual e executar uma consulta usando a função ai.if:

SET google_ml_integration.enable_ai_function_acceleration = on;

EXPLAIN (COSTS OFF) SELECT r.name
FROM restaurant_reviews r
WHERE ai.if('Is the following a positive review? Review: '||r.review) AND r.city = 'Los Angeles'
GROUP BY r.name
HAVING count(*) > 20
ORDER BY r.name;

Quando você usa a instrução EXPLAIN para analisar a consulta, o plano de consulta mostra um nó AI Function Apply:

                                       QUERY PLAN                                       
----------------------------------------------------------------------------------------
 GroupAggregate
   Group Key: name
   Filter: (count(*) > 20)
   ->  Sort
         Sort Key: name
         ->  AI Function Apply
               Filter: ai.if((('Is the following a positive review? Review: '::text || review)), NULL::character varying)
               ->  Index Scan using idx_restaurant_reviews_city on restaurant_reviews r
                     Index Cond: ((city)::text = 'Los Angeles'::text)

Verificar a aceleração da função de IA para consultas ai.rank

O exemplo a seguir mostra como ativar a aceleração da função de IA para a sessão atual e executar uma consulta usando a função ai.rank:

SET google_ml_integration.enable_ai_function_acceleration = on;

EXPLAIN (COSTS OFF) SELECT r.name, r.review
FROM restaurant_reviews r
WHERE r.city = 'Los Angeles'
ORDER BY ai.rank('Rank these reviews based on how much they emphasize high-quality ingredients. Review: ' || r.review) DESC
LIMIT 50;

Quando você usa a instrução EXPLAIN para analisar a consulta, o plano de consulta mostra um nó AI Function Apply:

                                       QUERY PLAN                                       
----------------------------------------------------------------------------------------
 Limit
  ->  Sort
        Sort Key: (ai.rank(('Rank these reviews based on how much they emphasize high-quality ingredients. Review: ' || r.review'), NULL)) DESC
        ->  AI Function Apply
              ->  Bitmap Heap Scan on restaurant_reviews r
                    Recheck Cond: (city = 'Los Angeles')
                    ->  Bitmap Index Scan on idx_restaurant_reviews_city
                          Index Cond: (city = 'Los Angeles')

O nó AIFunctionApply no plano de consulta indica que a consulta usou a aceleração da função de IA. Se esse nó não estiver presente, a consulta usou a execução padrão do PostgreSQL.

Limitações

  • Somente argumentos básicos para as funções são aceitos. Para ai.if e ai.rank, o argumento prompt precisa ser uma referência de coluna ou um literal de string concatenado com uma referência de coluna. Todos os outros argumentos precisam ser constantes simples. Exemplos de argumentos prompt aceitos incluem o seguinte:
    • ai.if(r.review)
    • ai.if('Is this true? : ' || r.review)
    • ai.rank(r.review)
    • ai.rank('Rate this review: ' || r.review)
  • Somente consultas SELECT com ai.if em cláusulas WHERE ou ai.rank em cláusulas ORDER BY são aceitas.
  • Somente uma função de IA por verificação de tabela é aceita.
  • Somente os modelos padrão do Gemini são aceitos. Para mais informações, consulte Modelos do Gemini. Para usar um modelo diferente, defina a flag google_ml_integration.default_llm_model como o ID do modelo que você quer usar.
  • O recurso está disponível apenas em regiões que oferecem suporte ao modelo gemini-2.5-flash-lite ou às regiões do modelo de LLM que você definiu usando a flag google_ml_integration.default_llm_model. Para mais informações, consulte Regiões com suporte.

A seguir