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.SEARCHnos nós do gráfico para fazer uma pesquisa semântica nas descrições das contas. - Use a função
AI.SEARCHnas 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
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Cloud de Confiance project.
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 theserviceusage.services.enablepermission. Learn how to grant roles.-
Verifique se você tem as seguintes funções no projeto: Editor de dados do BigQuery, Administrador do IAM do projeto
Verificar os papéis
-
No console do Cloud de Confiance , acesse a página IAM.
Acessar IAM - Selecione o projeto.
-
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.
- 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
-
No console do Cloud de Confiance , acesse a página IAM.
Acessar IAM - Selecione o projeto.
- Clique em Conceder acesso.
-
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.
- Clique em Selecionar um papel e pesquise o papel.
- Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
- Clique em Salvar.
-
gcloud
-
Instale a CLI do Google Cloud.
-
Configure a CLI gcloud para usar sua identidade federada.
Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init -
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ãoresourcemanager.projects.create. Saiba como conceder papéis.
-
Crie um projeto do Cloud de Confiance :
gcloud projects create PROJECT_ID
Substitua
PROJECT_IDpor 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_IDpelo nome do projeto do Cloud de Confiance .
-
Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .
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ãoserviceusage.services.enable. Saiba como conceder papéis.gcloud services enable bigquery.googleapis.com
-
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.projectIamAdmingcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Substitua:
PROJECT_ID: o ID do projeto.USER_IDENTIFIER: o identificador da sua conta de usuário conta. Para exemplos, consulte Representar usuários do pool de força de trabalho nas políticas do IAM.ROLE: o papel do IAM concedido à sua conta de usuário.
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
- Saiba mais sobre o BigQuery Graph.
- Saiba como criar e consultar um gráfico.
- Saiba mais sobre como criar um índice vetorial e realizar pesquisa semântica e RAG.