Pesquisar um gráfico

Neste tutorial, mostramos como realizar uma pesquisa semântica nos dados de gráfico usando a geração autônoma de embeddings e a função AI.SEARCH.

Objetivos

Este tutorial abrange as seguintes tarefas:

  • Crie tabelas com informações sobre pessoas, contas financeiras, propriedade e transferências de contas.
  • Use a geração autônoma de embeddings para simplificar seu fluxo de trabalho de manutenção de embeddings.
  • Crie um gráfico que defina as relações entre os dados armazenados nas suas tabelas.
  • Use a função AI.SEARCH nos nós do gráfico para fazer uma pesquisa semântica nas descrições das contas.
  • Use a função AI.SEARCH nas arestas do gráfico para fazer uma pesquisa semântica nas observações de transferência de conta.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Cloud de Confiance by S3NS:

  • BigQuery: You incur costs for the data that you process in BigQuery.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

Console

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the BigQuery API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  4. Verifique se você tem as seguintes funções no projeto: Editor de dados do BigQuery, Administrador do IAM do projeto

    Verificar os papéis

    1. No console do Cloud de Confiance , acesse a página IAM.

      Acessar IAM
    2. Selecione o projeto.
    3. Na coluna Principal, encontre todas as linhas que identificam você ou um grupo no qual você está incluído. Para saber em quais grupos você está incluído, entre em contato com o administrador.

    4. Em todas as linhas que especificam ou incluem você, verifique a coluna Papel para ver se a lista de papéis inclui os papéis necessários.

    Conceder os papéis

    1. No console do Cloud de Confiance , acesse a página IAM.

      Acessar IAM
    2. Selecione o projeto.
    3. Clique em Conceder acesso.
    4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o identificador de um usuário em um pool de identidades de força de trabalho. Saiba mais em Representar usuários do pool de força de trabalho nas políticas do IAM ou entre em contato com seu administrador.

    5. Clique em Selecionar um papel e pesquise o papel.
    6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
    7. Clique em Salvar.

gcloud

  1. Instale a CLI do Google Cloud.

  2. Configure a CLI gcloud para usar sua identidade federada.

    Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.

  3. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init
  4. Crie ou selecione um Cloud de Confiance projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.
    • Crie um projeto do Cloud de Confiance :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto Cloud de Confiance que você está criando.

    • Selecione o projeto Cloud de Confiance que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Cloud de Confiance .

  5. Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .

  6. Ative a API BigQuery:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    gcloud services enable bigquery.googleapis.com
  7. Atribua papéis à sua conta de usuário. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM: roles/bigquery.dataEditor, roles/resourcemanager.projectIamAdmin

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Substitua:

crie tabelas

Para armazenar as tabelas e o gráfico que você vai criar nos exemplos a seguir, crie um conjunto de dados. A consulta abaixo cria um conjunto de dados chamado graph_search:

CREATE SCHEMA IF NOT EXISTS graph_search;

As tabelas a seguir contêm informações sobre pessoas e contas, além das relações entre cada uma dessas entidades:

  • Person: informações sobre pessoas.
  • Account: informações sobre contas bancárias.
  • PersonOwnAccount: informações sobre quem é o proprietário de cada conta.
  • AccountTransferAccount: informações sobre transferências entre contas.

Para criar essas tabelas, execute as seguintes instruções CREATE TABLE:

CREATE OR REPLACE TABLE graph_search.Person (
  id               INT64,
  name             STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE OR REPLACE TABLE graph_search.Account (
  id                    INT64,
  create_time           TIMESTAMP,
  is_blocked            BOOL,
  description           STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
                          GENERATED ALWAYS AS (
                          AI.EMBED(description, model => 'embeddinggemma-300m')
                          ) STORED OPTIONS( asynchronous = TRUE ),
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE OR REPLACE TABLE graph_search.PersonOwnAccount (
  id               INT64 NOT NULL,
  account_id       INT64 NOT NULL,
  create_time      TIMESTAMP,
  PRIMARY KEY (id, account_id) NOT ENFORCED,
  FOREIGN KEY (id) REFERENCES graph_search.Person(id) NOT ENFORCED,
  FOREIGN KEY (account_id) REFERENCES graph_search.Account(id) NOT ENFORCED
);

CREATE OR REPLACE TABLE graph_search.AccountTransferAccount (
  id               INT64 NOT NULL,
  to_id            INT64 NOT NULL,
  amount           FLOAT64,
  create_time      TIMESTAMP NOT NULL,
  order_number     STRING,
  notes            STRING,
  notes_embedding  STRUCT<result ARRAY<FLOAT64>, status STRING>
                     GENERATED ALWAYS AS (
                     AI.EMBED(notes, model => 'embeddinggemma-300m')
                     ) STORED OPTIONS( asynchronous = TRUE ),
  PRIMARY KEY (id, to_id, create_time) NOT ENFORCED,
  FOREIGN KEY (id) REFERENCES graph_search.Account(id) NOT ENFORCED,
  FOREIGN KEY (to_id) REFERENCES graph_search.Account(id) NOT ENFORCED
);

As tabelas Account e AccountTransferAccount usam a geração autônoma de embeddings para manter os embeddings das colunas description e notes.

Neste tutorial, usamos o modelo embeddinggemma-300m porque ele é executado no BigQuery e funciona bem com strings curtas. Para strings mais longas que excedam 128 tokens, escolha um modelo de embedding diferente, como text-embedding-005. Para mais informações, leia sobre como escolher um modelo de embedding.

Inserir dados

As consultas a seguir inserem alguns dados de exemplo nas suas tabelas. As instruções INSERT omitem as colunas de incorporação, e o BigQuery as preenche automaticamente.

INSERT INTO graph_search.Account
  (id, create_time, is_blocked, description)
VALUES
  (7,"2020-01-10 06:22:20.222",false,"Fund for a refreshing tropical vacation"),
  (16,"2020-01-27 17:55:09.206",true,"Fund for a rainy day!"),
  (20,"2020-02-18 05:44:20.655",false,"Saving up for travel");

INSERT INTO graph_search.Person
  (id, name)
VALUES
  (1,"Alex"),
  (2,"Dana"),
  (3,"Lee");

INSERT INTO graph_search.AccountTransferAccount
  (id, to_id, amount, create_time, order_number, notes)
VALUES
  (7,16,300,"2020-08-29 15:28:58.647","304330008004315", "wedding present"),
  (7,16,100,"2020-10-04 16:55:05.342","304120005529714", "birthday gift"),
  (16,20,300,"2020-09-25 02:36:14.926","103650009791820", "for shared cost of dinner"),
  (20,7,500,"2020-10-04 16:55:05.342","304120005529714", "fees for tuition"),
  (20,16,200,"2020-10-17 03:59:40.247","302290001484851", "loved the lunch");

INSERT INTO graph_search.PersonOwnAccount
  (id, account_id, create_time)
VALUES
  (1,7,"2020-01-10 06:22:20.222"),
  (2,20,"2020-01-27 17:55:09.206"),
  (3,16,"2020-02-18 05:44:20.655");

Criar um gráfico

A consulta a seguir usa a instrução CREATE PROPERTY GRAPH para criar um gráfico chamado FinGraph no conjunto de dados graph_search. As tabelas Account e Person são as tabelas de nós. As tabelas AccountTransferAccount e PersonOwnAccount são as tabelas de aresta, que representam relações entre as tabelas de nó.

CREATE OR REPLACE PROPERTY GRAPH graph_search.FinGraph
NODE TABLES (graph_search.Account, graph_search.Person)
EDGE TABLES (
  graph_search.PersonOwnAccount
    SOURCE KEY (id) REFERENCES Person (id)
    DESTINATION KEY (account_id) REFERENCES Account (id)
    LABEL Owns,
  graph_search.AccountTransferAccount
    SOURCE KEY (id) REFERENCES Account (id)
    DESTINATION KEY (to_id) REFERENCES Account (id)
    LABEL Transfers
);

Pesquisar nós

As consultas a seguir mostram quem é o proprietário de contas para viagens de lazer e férias. A primeira consulta usa uma instrução DECLARE para criar uma variável chamada similar_account. A variável é inicializada na cláusula DEFAULT com uma chamada para AI.SEARCH que encontra contas cujas descrições são mais semanticamente semelhantes a accounts for leisure travel and vacation. A consulta define o argumento top_k como 2 na chamada para AI.SEARCH para limitar o número de resultados. A segunda consulta é uma consulta de gráfico que retorna o nome do proprietário da conta junto com a descrição dela.

DECLARE similar_account DEFAULT ((
SELECT ARRAY_AGG(base.id)
FROM
  AI.SEARCH(
    (SELECT * FROM graph_search.Account WHERE description_embedding IS NOT NULL),
    'description',
    'accounts for leisure travel and vacation',
    top_k => 2)
));

GRAPH graph_search.FinGraph
MATCH (p:Person)-[:Owns]->(a:Account)
WHERE a.id IN UNNEST(similar_account)
RETURN p.name, a.description;

O resultado será semelhante ao seguinte:

+------+-----------------------------------------+
| name | description                             |
+------+-----------------------------------------+
| Dana | Saving up for travel                    |
| Alex | Fund for a refreshing tropical vacation |
+------+-----------------------------------------+

Pesquisar arestas

As consultas a seguir mostram quem fez transferências de conta relacionadas a pagamentos de alimentos. A primeira consulta usa a função AI.SEARCH para preencher uma variável chamada food_transfers. Essa variável contém o número de ordem das transferências cuja observação associada é mais semanticamente semelhante a food. A consulta define o argumento top_k como 2 na chamada para AI.SEARCH para limitar o número de resultados. A segunda consulta é de gráfico e retorna o nome do proprietário da conta e a observação de transferência.

DECLARE food_transfers DEFAULT ((
SELECT ARRAY_AGG(base.order_number)
FROM
  AI.SEARCH(
    (SELECT * FROM graph_search.AccountTransferAccount WHERE notes_embedding IS NOT NULL),
    'notes',
    'food',
    top_k => 2)
));

GRAPH graph_search.FinGraph
MATCH (p:Person)-[:Owns]->(:Account)-[t:Transfers]->(:Account)
WHERE t.order_number IN UNNEST(food_transfers)
RETURN p.name, t.notes;

O resultado será semelhante ao seguinte:

+------+---------------------------+
| name | notes                     |
+------+---------------------------+
| Dana | loved the lunch           |
| Lee  | for shared cost of dinner |
+------+---------------------------+

Criar um índice vetorial

Índices vetoriais reduzem a latência e o custo computacional das suas pesquisas. As tabelas neste tutorial são muito pequenas para usar um índice vetorial, que é útil quando as tabelas são grandes, geralmente com milhões de linhas. O BigQuery oferece dois tipos de índice: IVF e TreeAH. Para mais informações sobre como criar um índice e escolher um tipo, consulte Gerenciar índices vetoriais.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

    Excluir um projeto do Cloud de Confiance :

    gcloud projects delete PROJECT_ID

A seguir