Esta página documenta a versão 16.8.0 do AlloyDB Omni usando a opção de implantação do Kubernetes. Escolha outra opção de implantação.

Esta página foi traduzida pela API Cloud Translation.

Registe e chame modelos de IA remotos no AlloyDB Omni

Selecione uma versão da documentação:

Para invocar previsões ou gerar incorporações através de um modelo, registe o ponto final do modelo na gestão de pontos finais de modelos.

Antes de registar um ponto final do modelo com a gestão de pontos finais do modelo, tem de ativar a extensão google_ml_integration e configurar a autenticação com base no fornecedor do modelo, se o ponto final do modelo exigir autenticação.

Certifique-se de que acede à base de dados com o postgres nome de utilizador predefinido.

Ative a extensão

Tem de adicionar e ativar a extensão google_ml_integration antes de poder começar a usar as funções associadas. A gestão de pontos finais de modelos requer que a extensão google_ml_integration esteja instalada.

Verifique se a flag da base de dados google_ml_integration.enable_model_support está definida como on para uma instância. Para mais informações sobre a definição de flags da base de dados, consulte o artigo Configure flags da base de dados.
Opcional: se a extensão google_ml_integration já estiver instalada, altere-a para atualizar para a versão mais recente:
```
    ALTER EXTENSION google_ml_integration UPDATE;
```

Adicione a extensão google_ml_integration através do psql:

  CREATE EXTENSION IF NOT EXISTS google_ml_integration;

Opcional: conceda autorização a um utilizador do PostgreSQL sem privilégios de superadministrador para gerir metadados do modelo:
```
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
```
Substitua NON_SUPER_USER pelo nome de utilizador do PostgreSQL que não seja superutilizador.

Ative a gestão de pontos finais de modelos na sua base de dados:

  ALTER SYSTEM SET google_ml_integration.enable_model_support=on;
  SELECT pg_reload_conf();

Certifique-se de que a conetividade de saída está ativada.

Configure a autenticação

As secções seguintes mostram como configurar a autenticação antes de registar um ponto final do modelo.

Configure a autenticação para o Vertex AI

Para usar os pontos finais do modelo Google Vertex AI, tem de adicionar autorizações do Vertex AI à conta de serviço que usou durante a instalação do AlloyDB Omni. Para mais informações, consulte o artigo Configure a instalação do AlloyDB Omni para consultar modelos baseados na nuvem.

Configure a autenticação através do Secret Manager

Este passo é opcional se o seu ponto final do modelo não processar a autenticação através do Secret Manager, por exemplo, se o seu ponto final do modelo usar cabeçalhos HTTP para transmitir informações de autenticação ou não usar autenticação.

Para criar e usar uma chave da API ou um token de autorização, conclua os seguintes passos:

Crie o Secret no Secret Manager. Para mais informações, consulte o artigo Crie um segredo e aceda a uma versão secreta.

O caminho secreto é usado na função SQL google_ml.create_sm_secret().
Conceda autorizações ao cluster do AlloyDB para aceder ao segredo.
```
  gcloud secrets add-iam-policy-binding 'SECRET_NAME' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"
```
Substitua o seguinte:
- SECRET_NAME: o nome do segredo no Secret Manager.
- SERVICE_ACCOUNT_ID: o ID da conta de serviço que criou no passo anterior. Certifique-se de que esta é a mesma conta que usou durante a instalação do AlloyDB Omni. Isto inclui o sufixo completo PROJECT_ID.iam.gserviceaccount.com. Por exemplo: my-service@my-project.iam.gserviceaccount.com
  
  Também pode conceder esta função à conta de serviço ao nível do projeto. Para mais informações, consulte o artigo Adicione uma associação de políticas de gestão de identidades e acessos

Configure a autenticação através de cabeçalhos

O exemplo seguinte mostra como configurar a autenticação através de uma função que devolve um objeto JSON que contém os cabeçalhos necessários para fazer um pedido ao modelo de incorporação.

  CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
    model_id VARCHAR(100),
    input_text TEXT
  )
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  DECLARE
    api_key VARCHAR(255) := 'API_KEY';
    header_json JSON;
  BEGIN
    header_json := json_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || api_key
    );
    RETURN header_json;
  END;
  $$;

Substitua o seguinte:

HEADER_GEN_FUNCTION: o nome da função de geração de cabeçalhos que pode usar quando regista um modelo.
API_KEY: a chave da API do fornecedor do modelo.

Modelos de incorporação de texto

Esta secção mostra como registar pontos finais de modelos com a gestão de pontos finais de modelos.

A gestão de pontos finais de modelos suporta alguns modelos de incorporação de texto e modelos genéricos da Vertex AI como pontos finais de modelos pré-registados. Pode usar diretamente o ID do modelo para gerar incorporações ou invocar previsões, com base no tipo de modelo. Para mais informações sobre os modelos pré-registados suportados, consulte o artigo Modelos do Vertex AI pré-registados.

Por exemplo, para chamar o modelo textembedding-gecko pré-registado, pode chamar diretamente o modelo através da função de incorporação:

SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Da mesma forma, para chamar o modelo gemini-1.5-pro:generateContent pré-registado, pode chamar diretamente o modelo através da função de previsão:

 SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-1.5-pro:generateContent',
            request_body => '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                    }
                ]
            }
        ]
        }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

Para gerar incorporações, veja como gerar incorporações para pontos finais de modelos pré-registados. Para invocar previsões, veja como invocar previsões para pontos finais de modelos pré-registados.

Modelos de incorporação de texto com suporte integrado

A gestão de pontos finais de modelos oferece suporte integrado para alguns modelos do Vertex AI e da OpenAI. Para ver a lista de modelos com suporte integrado, consulte o artigo Modelos com suporte integrado.

Para modelos com suporte integrado, pode definir o nome qualificado como o nome qualificado do modelo e especificar o URL do pedido. A gestão de pontos finais de modelos identifica automaticamente o modelo e configura as funções de transformação predefinidas.

Modelos de incorporação da Vertex AI

Os passos seguintes mostram como registar modelos do Vertex AI com suporte integrado. O ponto final do modelo text-embedding-005 e text-multilingual-embedding-002 é usado como exemplo.

Para o AlloyDB Omni, certifique-se de que configura o AlloyDB Omni para consultar modelos da Vertex AI baseados na nuvem.

Crie e ative a extensão google_ml_integration.
Associe à sua base de dados através do psql.

Chame a função de criação de modelos para adicionar o ponto final do modelo:

text-embedding-005

  CALL
    google_ml.create_model(
      model_id => 'text-embedding-005',
      model_request_url => 'publishers/google/models/text-embedding-005',
      model_provider => 'google',
      model_qualified_name => 'text-embedding-005',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam');

text-multilingual-embedding-002

  CALL
    google_ml.create_model(
      model_id => 'text-multilingual-embedding-002',
      model_request_url => 'publishers/google/models/text-multilingual-embedding-002',
      model_provider => 'google',
      model_qualified_name => 'text-multilingual-embedding-002',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam'
      model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
      model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');

O URL de pedido gerado pela função refere-se ao projeto associado à conta de serviço do AlloyDB Omni. Se quiser fazer referência a outro projeto, certifique-se de que especifica o model_request_url explicitamente.

Se o modelo estiver armazenado num projeto e numa região diferentes do cluster do AlloyDB, defina o URL do pedido como projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID, em que REGION_ID é a região onde o modelo está alojado e MODEL_ID é o nome do modelo qualificado.

Além disso, conceda a função de utilizador do Vertex AI (roles/aiplatform.user) à conta de serviço do projeto onde o AlloyDB Omni está instalado para que seja possível aceder ao modelo alojado no outro projeto.

Abrir modelo de incorporação de texto de IA

A extensão google_ml_integration configura automaticamente as funções de transformação predefinidas e invoca chamadas para os modelos OpenAI remotos. Para ver a lista de modelos da OpenAI com suporte integrado, consulte o artigo Modelos com suporte integrado.

O exemplo seguinte adiciona o ponto final do modelo text-embedding-ada-002 OpenAI. Pode registar os pontos finais do modelo text-embedding-3-small e text-embedding-3-large da OpenAI através dos mesmos passos e definindo os nomes qualificados do modelo específicos dos modelos.

Associe à sua base de dados através do psql.
Crie e ative a extensão google_ml_integration.
Adicione a chave da API OpenAI como um segredo ao Secret Manager para autenticação.
Chame o segredo armazenado no Secret Manager:
```
CALL
google_ml.create_sm_secret(
  secret_id => 'SECRET_ID',
  secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
```
Substitua o seguinte:
- SECRET_ID: o ID secreto que define e que é usado posteriormente quando regista um ponto final do modelo, por exemplo, key1.
- SECRET_MANAGER_SECRET_ID: o ID secreto definido no Secret Manager quando criou o segredo.
- PROJECT_ID: o ID do seu projeto Google Cloud .
- VERSION_NUMBER: o número da versão do ID secreto.
Chame a função de criação de modelos para registar o ponto final do modelo text-embedding-ada-002:
```
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'open_ai',
    model_type => 'text_embedding',
    model_qualified_name => 'text-embedding-ada-002',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID');
```
Substitua o seguinte:
- MODEL_ID: um ID exclusivo para o ponto final do modelo que define. Este ID do modelo é referenciado para metadados que o ponto final do modelo precisa para gerar incorporações ou invocar previsões.
- SECRET_ID: o ID secreto que usou anteriormente no procedimento google_ml.create_sm_secret().

Para gerar incorporações, veja como gerar incorporações para pontos finais de modelos com suporte integrado.

Modelo de incorporação de texto alojado de forma personalizada

Esta secção mostra como registar um ponto final de modelo alojado de forma personalizada, juntamente com a criação de funções de transformação e, opcionalmente, cabeçalhos HTTP personalizados. Todos os pontos finais de modelos alojados de forma personalizada são suportados, independentemente do local onde estão alojados.

O exemplo seguinte adiciona o ponto final do modelo personalizado custom-embedding-model alojado pela Cymbal. As funções de transformação cymbal_text_input_transform e cymbal_text_output_transform são usadas para transformar o formato de entrada e saída do modelo no formato de entrada e saída da função de previsão.

Para registar pontos finais de modelos de incorporação de texto alojados de forma personalizada, conclua os seguintes passos:

Associe à sua base de dados através do psql.
Crie e ative a extensão google_ml_integration.
Opcional: adicione a chave da API como um segredo ao Secret Manager para autenticação.
Chame o segredo armazenado no Secret Manager:
```
CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
```
Substitua o seguinte:
- SECRET_ID: o ID secreto que define e que é usado posteriormente quando regista um ponto final do modelo, por exemplo, key1.
- SECRET_MANAGER_SECRET_ID: o ID secreto definido no Secret Manager quando criou o segredo.
- PROJECT_ID: o ID do seu projeto Google Cloud .
- VERSION_NUMBER: o número da versão do ID secreto.
Nota: o Secret Manager gera um cabeçalho Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER para autenticação por predefinição. Se este formato corresponder ao formato do token de autorização do portador do ponto final do modelo, não tem de gerar cabeçalhos de autorização usando a função de geração de cabeçalhos.

Crie as funções de transformação de entrada e saída com base na seguinte assinatura para os pontos finais do modelo de incorporação de texto da função de previsão. Para mais informações sobre como criar funções de transformação, consulte o exemplo de funções de transformação.

Seguem-se exemplos de funções de transformação específicas do custom-embedding-model ponto final do modelo de incorporação de texto:

-- Input Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;
-- Output Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
  SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
  RETURN transformed_output;
END;
$$;

Chame a função de criação de modelos para registar o ponto final do modelo de incorporação personalizado:
```
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'REQUEST_URL',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_in_transform_fn => 'cymbal_text_input_transform',
    model_out_transform_fn => 'cymbal_text_output_transform');
```
Substitua o seguinte:
- MODEL_ID: obrigatório. Um ID exclusivo para o ponto final do modelo que define, por exemplo, custom-embedding-model. Este ID do modelo é referenciado para metadados que o ponto final do modelo precisa para gerar incorporações ou invocar previsões.
- REQUEST_URL: obrigatório. O ponto final específico do modelo quando adiciona incorporação de texto personalizada e pontos finais de modelos genéricos, por exemplo, https://cymbal.com/models/text/embeddings/v1.
- MODEL_QUALIFIED_NAME: obrigatório se o ponto final do modelo usar um nome qualificado. O nome totalmente qualificado, caso o ponto final do modelo tenha várias versões.
- SECRET_ID: o ID secreto que usou anteriormente no procedimento google_ml.create_sm_secret().

Modelos genéricos

Esta secção mostra como registar qualquer ponto final de modelo genérico que esteja disponível num fornecedor de modelos alojados, como o Hugging Face, a OpenAI, a Vertex AI, a Anthropic ou qualquer outro fornecedor. Esta secção mostra exemplos para registar um ponto final de modelo genérico alojado no Hugging Face, um modelo genérico gemini-pro do Model Garden do Vertex AI e o ponto final de modelo claude-haiku.

Pode registar qualquer ponto final de modelo genérico, desde que a entrada e a saída estejam no formato JSON. Com base nos metadados do ponto final do modelo, pode ter de gerar cabeçalhos HTTP ou definir URLs de pedidos.

Para mais informações sobre modelos genéricos pré-registados e modelos com suporte integrado, consulte o artigo Modelos suportados.

Modelo do Gemini

Uma vez que alguns modelos gemini-pro estão pré-registados, pode chamar diretamente o ID do modelo para invocar previsões. Certifique-se de que configura o AlloyDB Omni para consultar modelos da Vertex AI baseados na nuvem.

O exemplo seguinte usa o ponto final do modelo gemini-1.5-pro:generateContent do Vertex AI Model Garden.

Associe à sua base de dados através do psql.
Crie e ative a extensão google_ml_integration.

Invocar previsões através do ID do modelo pré-registado:

SELECT
    json_array_elements(
    google_ml.predict_row(
        model_id => 'gemini-1.5-pro:generateContent',
        request_body => '{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                }
            ]
        }
    ]
    }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

Modelo genérico no Hugging Face

O exemplo seguinte adiciona o ponto final do modelo de classificação personalizada facebook/bart-large-mnlialojado no Hugging Face.

Associe à sua base de dados através do psql.
Crie e ative a extensão google_ml_integration.
Adicione a chave da API OpenAI como um segredo ao Secret Manager para autenticação. Se já tiver criado um segredo para qualquer outro modelo da OpenAI, pode reutilizar o mesmo segredo.
Chame o segredo armazenado no Secret Manager:
```
CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
```
Substitua o seguinte:
- SECRET_ID: o ID secreto que define e que é usado posteriormente quando regista um ponto final do modelo.
- SECRET_MANAGER_SECRET_ID: o ID secreto definido no Secret Manager quando criou o segredo.
- PROJECT_ID: o ID do seu projeto Google Cloud .
- VERSION_NUMBER: o número da versão do ID secreto.
Chame a função de criação de modelos para registar o ponto final do modelo facebook/bart-large-mnli:
```
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'hugging_face',
    model_request_url => 'REQUEST_URL',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID');
```
Substitua o seguinte:
- MODEL_ID: um ID exclusivo para o ponto final do modelo que define, por exemplo, custom-classification-model. Este ID do modelo é referenciado para metadados que o ponto final do modelo precisa para gerar incorporações ou invocar previsões.
- REQUEST_URL: o ponto final específico do modelo quando adiciona incorporação de texto personalizada e pontos finais de modelos genéricos, por exemplo, https://api-inference.huggingface.co/models/facebook/bart-large-mnli.
- MODEL_QUALIFIED_NAME: o nome totalmente qualificado da versão do ponto final do modelo, por exemplo, facebook/bart-large-mnli.
- SECRET_ID: o ID secreto que usou anteriormente no procedimento google_ml.create_sm_secret().

Modelo genérico da Anthropic

O exemplo seguinte adiciona o ponto final do modelo claude-3-opus-20240229. A gestão de pontos finais de modelos fornece a função de cabeçalho necessária para registar modelos da Anthropic.

Certifique-se de que configura o AlloyDB Omni para consultar modelos da Vertex AI baseados na nuvem.

Associe à sua base de dados através do psql.
Crie e ative a extensão google_ml_integration.
Secret Manager
1. Adicione o token de portador como um segredo ao Secret Manager para autenticação.
2. Chame o segredo armazenado no Secret Manager:
  CALL google_ml.create_sm_secret( secret_id => 'SECRET_ID', secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
  Substitua o seguinte:
  - SECRET_ID: o ID secreto que define e que é usado posteriormente quando regista um ponto final do modelo.
  - SECRET_MANAGER_SECRET_ID: o ID secreto definido no Secret Manager quando criou o segredo.
  - PROJECT_ID: o ID do seu projeto Google Cloud .
  - VERSION_NUMBER: o número da versão do ID secreto.
3. Chame a função de criação de modelos para registar o ponto final do modelo claude-3-opus-20240229.
  CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'anthropic', model_request_url => 'REQUEST_URL', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID', generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');
  Substitua o seguinte:
  - MODEL_ID: um ID exclusivo para o ponto final do modelo que define, por exemplo, anthropic-opus. Este ID do modelo é referenciado para metadados que o ponto final do modelo precisa para gerar incorporações ou invocar previsões.
  - REQUEST_URL: o ponto final específico do modelo quando adiciona incorporação de texto personalizada e pontos finais de modelos genéricos, por exemplo, https://api.anthropic.com/v1/messages.
Cabeçalho de autorização
1. Use a função de geração de cabeçalhos predefinida google_ml.anthropic_claude_header_gen_fn ou crie uma função de geração de cabeçalhos.
  CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON) RETURNS JSON LANGUAGE plpgsql AS $$ #variable_conflict use_variable BEGIN RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON; END; $$;
  Substitua o seguinte:
  - ANTHROPIC_API_KEY: a chave da API da Anthropic.
  - ANTHROPIC_VERSION (Opcional): a versão específica do modelo que quer usar, por exemplo, 2023-06-01.
2. Chame a função de criação de modelos para registar o ponto final do modelo claude-3-opus-20240229.
  CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'anthropic', model_request_url => 'REQUEST_URL', generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');
  Substitua o seguinte:
  - MODEL_ID: um ID exclusivo para o ponto final do modelo que define, por exemplo, anthropic-opus. Este ID do modelo é referenciado para metadados que o ponto final do modelo precisa para gerar incorporações ou invocar previsões.
  - REQUEST_URL: o ponto final específico do modelo quando adiciona incorporação de texto personalizada e pontos finais de modelos genéricos, por exemplo, https://api.anthropic.com/v1/messages.

Para mais informações, veja como invocar previsões para pontos finais de modelos genéricos.

O que se segue?

Saiba mais acerca da referência de gestão de pontos finais de modelos.
Use modelos de exemplo para registar pontos finais de modelos.