Técnicas práticas de observabilidade para o aplicativo de IA generativa em Python

1. Visão geral

Os aplicativos de IA generativa exigem observabilidade como qualquer outro. Há técnicas de observabilidade especiais necessárias para a IA generativa?

Neste laboratório, você vai criar um aplicativo simples do Gen AI. Implante no Cloud Run. E instrumente com recursos essenciais de monitoramento e geração de registros usando os serviços e produtos de observabilidade do Google Cloud.

O que você vai aprender

  • Criar um aplicativo que usa a Vertex AI com o editor do Cloud Shell
  • Armazenar o código do aplicativo no GitHub
  • Use a CLI gcloud para implantar o código-fonte do seu aplicativo no Cloud Run
  • Adicionar recursos de monitoramento e registro ao seu aplicativo de IA generativa
  • Como usar métricas com base em registros
  • Implementar a geração de registros e o monitoramento com o SDK do Open Telemetry
  • Receba insights sobre o processamento responsável de dados de IA

2. Pré-requisitos

Se você ainda não tem uma Conta do Google, crie uma.

3. Configurar o projeto

  1. Faça login no Console do Google Cloud com sua Conta do Google.
  2. Crie um novo projeto ou escolha reutilizar um projeto atual. Anote o ID do projeto que você acabou de criar ou selecionar.
  3. Ative o faturamento do projeto.
    • A conclusão deste laboratório deve custar menos de US $5 em custos de faturamento.
    • Siga as etapas no final deste laboratório para excluir recursos e evitar cobranças.
    • Novos usuários estão qualificados para o teste sem custo financeiro de US$300.
  4. Confirme se o faturamento está ativado em Meus projetos no Cloud Billing
      .
    • Se o novo projeto mostrar Billing is disabled na coluna Billing account:
      1. Clique nos três pontos na coluna Actions.
      2. Clique em Mudar faturamento.
      3. Selecione a conta de faturamento que você quer usar.
    • Se você estiver participando de um evento ao vivo, a conta provavelmente será chamada de Conta de faturamento de teste do Google Cloud Platform.

4. Preparar o editor do Cloud Shell

  1. Acesse o editor do Cloud Shell. Se você receber a mensagem a seguir solicitando a autorização do Cloud Shell para chamar o gcloud com suas credenciais, clique em Autorizar para continuar.
    Clique para autorizar o Cloud Shell
  2. Abrir janela do terminal
    1. Clique no menu de navegação Ícone do menu de navegação.
    2. Clique em Terminal.
    3. Clique em Novo terminal
      Abrir um novo terminal no editor do Cloud Shell.
  3. No terminal, configure o ID do projeto:
    gcloud config set project [PROJECT_ID]
    Substitua [PROJECT_ID] pelo ID do seu projeto. Por exemplo, se o ID do projeto for lab-example-project, o comando será:
    gcloud config set project lab-project-id-example
    Se você receber a seguinte mensagem informando que o gcloud está solicitando suas credenciais para a API GCPI, clique em Autorizar para continuar.
    Clique para autorizar o Cloud Shell
    Se a execução for bem-sucedida, você verá a seguinte mensagem:
    Updated property [core/project].
    Se você receber uma WARNING e receber uma solicitação Do you want to continue (Y/N)?, provavelmente inseriu o ID do projeto incorretamente. Pressione N, pressione Enter e tente executar o comando gcloud config set project novamente depois de encontrar o ID do projeto correto.
  4. (Opcional) Se você tiver problemas para encontrar o ID do projeto, execute o comando a seguir para conferir o ID de todos os seus projetos classificados por data de criação em ordem decrescente:
    gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime

5. ative as APIs do Google

No terminal, ative as APIs do Google necessárias para este laboratório:

gcloud services enable \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     aiplatform.googleapis.com \
     logging.googleapis.com \
     monitoring.googleapis.com \
     cloudtrace.googleapis.com

Esse comando leva algum tempo para ser concluído. Uma mensagem semelhante a esta vai aparecer:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

Se você receber uma mensagem de erro começando com ERROR: (gcloud.services.enable) HttpError accessing e contendo detalhes de erro como abaixo, tente novamente o comando após um atraso de um a dois minutos.

"error": {
  "code": 429,
  "message": "Quota exceeded for quota metric 'Mutate requests' and limit 'Mutate requests per minute' of service 'serviceusage.googleapis.com' ...",
  "status": "RESOURCE_EXHAUSTED",
  ...
}

6. Criar um aplicativo Python de IA generativa

Nesta etapa, você vai escrever um código do aplicativo simples baseado em solicitações que usa o modelo Gemini para mostrar 10 curiosidades sobre um animal de sua escolha. Siga as instruções para criar o código do aplicativo.

  1. No terminal, crie o diretório codelab-o11y:
    mkdir ~/codelab-o11y
  2. Mude o diretório atual para codelab-o11y:
    cd ~/codelab-o11y
  3. Crie o requirements.txt com a lista de dependências:
    cat > requirements.txt << EOF
Flask==3.0.0
gunicorn==23.0.0
google-cloud-aiplatform==1.59.0
google-auth==2.32.0
EOF
  4. Crie um arquivo main.py e abra-o no editor do Cloud Shell:
    cloudshell edit main.py
    Um arquivo vazio vai aparecer na janela do editor acima do terminal. A tela vai ficar assim:
    Mostrar o editor do Cloud Shell depois de começar a editar o main.py
  5. Copie e cole o código abaixo no arquivo main.py aberto:
    import os
from flask import Flask, request
import google.auth
import vertexai
from vertexai.generative_models import GenerativeModel

_, project = google.auth.default()
app = Flask(__name__)

@app.route('/')
def fun_facts():
    vertexai.init(project=project, location='us-central1')
    model = GenerativeModel('gemini-1.5-flash')
    animal = request.args.get('animal', 'dog') 
    prompt = f'Give me 10 fun facts about {animal}. Return this as html without backticks.'
    response = model.generate_content(prompt)
    return response.text

if __name__ == '__main__':
    app.run(debug=True, host='0.0.0.0', port=int(os.environ.get('PORT', 8080)))
    Depois de alguns segundos, o editor do Cloud Shell vai salvar o código automaticamente.

Implantar o código do aplicativo de IA generativa no Cloud Run

  1. Na janela do terminal, execute o comando para implantar o código-fonte do aplicativo no Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se você receber uma mensagem como a abaixo, o comando vai criar um novo repositório. Clique em Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    O processo de implantação pode levar alguns minutos. Depois que o processo de implantação for concluído, você vai receber uma saída como esta:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. Copie o URL do serviço do Cloud Run exibido para uma guia ou janela separada no navegador. Como alternativa, execute o comando a seguir no terminal para imprimir o URL do serviço e clique no URL mostrado enquanto pressiona a tecla Ctrl para abrir o URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando o URL é aberto, você pode receber um erro 500 ou a mensagem:
    Sorry, this is just a placeholder...
    Isso significa que os serviços não concluíram a implantação. Aguarde alguns instantes e atualize a página. No final, você vai encontrar um texto que começa com Curiosidades sobre cães e contém 10 curiosidades sobre cães.

Tente interagir com o aplicativo para conferir curiosidades sobre diferentes animais. Para fazer isso, anexe o parâmetro animal ao URL, como ?animal=[ANIMAL], em que [ANIMAL] é o nome de um animal. Por exemplo, adicione ?animal=cat para receber 10 curiosidades sobre gatos ou ?animal=sea turtle para receber 10 curiosidades sobre tartarugas marinhas.

7. Auditar suas chamadas da API Vertex

A auditoria das chamadas de API do Google responde a perguntas como "Quem chamou uma API específica, onde e quando?". A auditoria é importante quando você soluciona problemas no aplicativo, investiga o consumo de recursos ou realiza análises forenses de software.

Os registros de auditoria permitem acompanhar atividades administrativas e do sistema, além de registrar chamadas para operações de "leitura de dados" e "gravação de dados" da API. Para auditar solicitações da Vertex AI para gerar conteúdo, ative os registros de auditoria "Leitura de dados" no console do Cloud.

  1. Clique no botão abaixo para abrir a página "Registros de auditoria" no console do Cloud

  2. Verifique se a página tem o projeto que você criou para este laboratório selecionado. O projeto selecionado aparece no canto superior esquerdo da página, no menu de navegação:
    Menu suspenso de projetos do Console do Google Cloud
    Se necessário, selecione o projeto correto na caixa de combinação.
  3. Na tabela Configuração dos registros de auditoria de acesso a dados, na coluna "Serviço", encontre o serviço Vertex AI API e selecione-o marcando a caixa de seleção à esquerda do nome do serviço.
    Selecionar a API Vertex AI
  4. No painel de informações à direita, selecione o tipo de auditoria "Leitura de dados".
    Verificar os registros de leitura de dados
  5. Clique em Salvar.

Para gerar registros de auditoria, abra o URL do serviço. Atualize a página enquanto muda o valor do parâmetro ?animal= para obter resultados diferentes.

Acessar registros de auditoria

  1. Clique no botão abaixo para abrir a página do Logs Explorer no console do Cloud:

  2. Cole o filtro a seguir no painel "Consulta".
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
    O painel "Query" é um editor localizado na parte de cima da página "Explorador de registros":
    Consultar registros de auditoria
  3. Clique em Executar consulta.
  4. Selecione uma das entradas do registro de auditoria e abra os campos para inspecionar as informações capturadas no registro.
    É possível conferir detalhes sobre a chamada da API Vertex, incluindo o método e o modelo usado. Você também pode conferir a identidade do invocador e quais permissões autorizaram a chamada.

8. Registrar interações com a IA generativa

Não é possível encontrar parâmetros de solicitação de API ou dados de resposta nos registros de auditoria. No entanto, essas informações podem ser importantes para solucionar problemas de análise de aplicativos e fluxos de trabalho. Nesta etapa, vamos preencher essa lacuna adicionando o registro do aplicativo. A geração de registros usa o pacote logging do Python clássico. Embora no ambiente de produção você possa usar um framework de geração de registros diferente, os princípios são os mesmos.

O pacote logging do Python não sabe como gravar registros no Google Cloud. Ele oferece suporte à gravação na saída padrão (stderr por padrão) ou em um arquivo. No entanto, o Cloud Run tem recursos que capturam informações impressas na saída padrão e as transferem automaticamente para o Cloud Logging. Siga as instruções abaixo para adicionar recursos de geração de registros ao nosso aplicativo de IA generativa.

  1. Volte para a janela (ou guia) do Cloud Shell no navegador.
  2. No terminal, abra novamente main.py:
    cloudshell edit ~/codelab-o11y/main.py
  3. Faça as seguintes modificações no código do aplicativo:
    1. Encontre a última instrução de importação. Deve ser a linha 5:
      from vertexai.generative_models import GenerativeModel
      Coloque o cursor na próxima linha (linha 6) e cole o bloco de código abaixo.
      import sys, json, logging
class JsonFormatter(logging.Formatter):
    def format(self, record):
        json_log_object = {
            'severity': record.levelname,
            'message': record.getMessage(),
        }
        json_log_object.update(getattr(record, 'json_fields', {}))
        return json.dumps(json_log_object)
logger = logging.getLogger(__name__)
sh = logging.StreamHandler(sys.stdout)
sh.setFormatter(JsonFormatter())
logger.addHandler(sh)
logger.setLevel(logging.DEBUG)
    2. Encontre o código que chama o modelo para gerar conteúdo. Ela precisa estar na linha 30:
      response = model.generate_content(prompt)
      Coloque o cursor no início da PRÓXIMA linha (linha 31) e cole o bloco de código abaixo.
          json_fields = {
         'animal': animal,
         'prompt': prompt,
         'response': response.to_dict(),
    }
    logger.debug('content is generated', extra={'json_fields': json_fields})
    Essas mudanças configuram o registro padrão do Python para usar um formatador personalizado para gerar JSON com string que segue as diretrizes de formatação estruturada. A geração de registros é configurada para imprimir registros em stdout, onde é coletada pelo agente de geração de registros do Cloud Run e ingestão assíncrona no Cloud Logging. Os registros capturam o parâmetro animal da solicitação e o comando e a resposta do modelo.Após alguns segundos, o editor do Cloud Shell salva suas alterações automaticamente.

Implantar o código do aplicativo de IA generativa no Cloud Run

  1. Na janela do terminal, execute o comando para implantar o código-fonte do aplicativo no Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se você receber uma mensagem como a abaixo, o comando vai criar um novo repositório. Clique em Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    O processo de implantação pode levar alguns minutos. Depois que o processo de implantação for concluído, você vai receber uma saída como esta:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. Copie o URL do serviço do Cloud Run exibido para uma guia ou janela separada no navegador. Como alternativa, execute o comando a seguir no terminal para imprimir o URL do serviço e clique no URL mostrado enquanto pressiona a tecla Ctrl para abrir o URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando o URL é aberto, você pode receber um erro 500 ou a mensagem:
    Sorry, this is just a placeholder...
    Isso significa que os serviços não concluíram a implantação. Aguarde alguns instantes e atualize a página. No final, você vai encontrar um texto que começa com Curiosidades sobre cães e contém 10 curiosidades sobre cães.

Para gerar registros do aplicativo, abra o URL do serviço. Atualize a página enquanto muda o valor do parâmetro ?animal= para obter resultados diferentes.
Para conferir os registros do aplicativo, faça o seguinte:

  1. Clique no botão abaixo para abrir a página do Logs Explorer no console do Cloud:

  2. Cole o seguinte filtro no painel de consulta (#2 na interface do Gerenciador de registros):
    LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
  3. Clique em Executar consulta.

O resultado da consulta mostra registros com o comando e a resposta da Vertex AI, incluindo as classificações de segurança.

9. Contar interações com a IA generativa

O Cloud Run grava métricas gerenciadas que podem ser usadas para monitorar os serviços implantados. As métricas de monitoramento gerenciadas pelo usuário oferecem mais controle sobre os dados e a frequência da atualização da métrica. Para implementar essa métrica, é necessário escrever um código que colete dados e os grave no Cloud Monitoring. Consulte a próxima etapa (opcional) para saber como implementar usando o SDK do OpenTelemetry.

Esta etapa mostra uma alternativa para implementar a métrica do usuário no código: métricas com base em registros. As métricas com base em registros permitem gerar métricas de monitoramento com base nas entradas de registro que seu aplicativo grava no Cloud Logging. Vamos usar os registros do aplicativo que implementamos na etapa anterior para definir uma métrica com base em registros do contador de tipo. A métrica vai contar o número de chamadas bem-sucedidas para a API Vertex.

  1. Observe a janela do Explorador de registros que usamos na etapa anterior. No painel "Consulta", localize o menu suspenso Ações e clique nele para abrir. Consulte a captura de tela abaixo para encontrar o menu:
    Barra de ferramentas dos resultados da consulta com o menu suspenso &quot;Ações&quot;
  2. No menu aberto, selecione Criar métrica para abrir o painel Criar métrica com base em registros.
  3. Siga estas etapas para configurar uma nova métrica de contagem no painel Criar métrica com base em registros:
    1. Defina o Tipo de métrica: selecione Contador.
    2. Defina os seguintes campos na seção Detalhes:
      • Nome da métrica de registro: defina o nome como model_interaction_count. Algumas restrições de nomenclatura se aplicam. Consulte Solução de problemas para mais detalhes.
      • Descrição: insira uma descrição para a métrica. Por exemplo, Number of log entries capturing successful call to model inference.
      • Unidades: deixe em branco ou insira o dígito 1.
    3. Deixe os valores na seção Seleção de filtro. O campo Build filter tem o mesmo filtro que usamos para conferir os registros do aplicativo.
    4. (Opcional) Adicione um rótulo que ajude a contar o número de chamadas para cada animal. OBSERVAÇÃO: esse rótulo pode aumentar muito a cardinalidade da métrica e não é recomendado para uso na produção:
      1. Clique em Adicionar rótulo.
      2. Defina os seguintes campos na seção Rótulos:
        • Nome do rótulo: defina o nome como animal.
        • Descrição: insira a descrição do rótulo. Por exemplo, Animal parameter.
        • Tipo de rótulo: selecione STRING.
        • Nome do campo: digite jsonPayload.animal.
        • Expressão regular: deixe em branco.
      3. Clique em Concluir.
    5. Clique em Criar métrica para criá-la.

Também é possível criar uma métrica com base em registros na página Métricas com base em registros usando o comando CLI gcloud logging metrics create ou o recurso do Terraform google_logging_metric.

Para gerar dados de métrica, abra o URL do serviço. Atualize a página aberta várias vezes para fazer várias chamadas para o modelo. Como antes, tente usar animais diferentes no parâmetro.

Insira a consulta PromQL para pesquisar os dados de métrica com base em registros. Para inserir uma consulta em PromQL, faça o seguinte:

  1. Clique no botão abaixo para abrir a página do Metrics Explorer no console do Cloud:

  2. Na barra de ferramentas do painel do criador de consultas, selecione o botão < > MQL ou < > PromQL. Confira a imagem abaixo para ver a localização do botão.
    Local do botão MQL no Metrics Explorer
  3. Verifique se PromQL está selecionado no botão de alternância Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.
  4. Insira sua consulta no editor Consultas:
    sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
    Para mais informações sobre como usar o PromQL, consulte PromQL no Cloud Monitoring.
  5. Selecione Executar consulta. Você vai encontrar um gráfico de linhas semelhante a esta captura de tela:
    Mostrar métricas consultadas

    Observe que, quando a opção Execução automática está ativada, o botão Executar consulta não é exibido.

10. (Opcional) Usar a telemetria aberta para monitoramento e rastreamento

Como mencionado na etapa anterior, é possível implementar métricas usando o SDK do OpenTelemetry (Otel). O uso do OTel em arquiteturas de microsserviços é uma prática recomendada. Esta etapa descreve o seguinte:

  • Como inicializar componentes do OTel para oferecer suporte ao rastreamento e monitoramento do aplicativo
  • Como preencher a configuração do OTel com metadados de recursos do ambiente do Cloud Run
  • Como instrumentar um aplicativo flask com recursos de rastreamento automático
  • Implementar uma métrica de contador para monitorar o número de chamadas de modelo bem-sucedidas
  • Correlacionar o rastreamento com os registros do aplicativo

A arquitetura recomendada para serviços no nível do produto é usar o OTel collector para coletar e processar todos os dados de observabilidade de um ou mais serviços. O código desta etapa não usa o coletor para simplificar. Em vez disso, ele usa exportações do OTel que gravam dados diretamente no Google Cloud.

Configurar componentes do OTel para rastreamento e monitoramento de métricas

  1. Volte para a janela (ou guia) do Cloud Shell no navegador.
  2. No terminal, atualize o requirements.txt com uma lista adicional de dependências:
    cat >> ~/codelab-o11y/requirements.txt << EOF
opentelemetry-api==1.24.0
opentelemetry-sdk==1.24.0
opentelemetry-exporter-otlp-proto-http==1.24.0
opentelemetry-instrumentation-flask==0.45b0
opentelemetry-instrumentation-requests==0.45b0
opentelemetry-exporter-gcp-trace==1.7.0
opentelemetry-exporter-gcp-monitoring==1.7.0a0   
EOF
  3. Crie um novo arquivo setup_opentelemetry.py:
    cloudshell edit ~/codelab-o11y/setup_opentelemetry.py
    Um arquivo vazio vai aparecer na janela do editor acima do terminal.
  4. Copie e cole o código abaixo no arquivo setup_opentelemetry.py aberto:
    import os

from opentelemetry import metrics
from opentelemetry import trace
from opentelemetry.exporter.cloud_monitoring import CloudMonitoringMetricsExporter
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.resourcedetector.gcp_resource_detector import GoogleCloudResourceDetector
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import get_aggregated_resources, Resource, CLOUD_ACCOUNT_ID, SERVICE_NAME
from opentelemetry.sdk.trace.export import BatchSpanProcessor

resource = get_aggregated_resources(
    [GoogleCloudResourceDetector(raise_on_error=True)]
)
resource = resource.merge(Resource.create(attributes={
    SERVICE_NAME: os.getenv("K_SERVICE"),
}))

meter_provider = MeterProvider(
    resource=resource,
    metric_readers=[
        PeriodicExportingMetricReader(
            CloudMonitoringMetricsExporter(), export_interval_millis=5000
        )
    ],
)
metrics.set_meter_provider(meter_provider)
meter = metrics.get_meter(__name__)

trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(CloudTraceSpanExporter(
    # send all resource attributes
    resource_regex=r".*"
))
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)

def google_trace_id_format(trace_id: int) -> str:
    project_id = resource.attributes[CLOUD_ACCOUNT_ID]
    return f'projects/{project_id}/traces/{trace.format_trace_id(trace_id)}'
    Depois de alguns segundos, o editor do Cloud Shell vai salvar o código automaticamente.

Instrumentar o código do aplicativo com recursos de rastreamento e monitoramento usando o OTel

  1. No terminal, abra novamente main.py:
    cloudshell edit ~/codelab-o11y/main.py
  2. Faça as seguintes modificações no código do aplicativo:
    1. Antes da linha import os (linha 1), insira o seguinte código (observe a linha vazia no final):
      from setup_opentelemetry import google_trace_id_format
from opentelemetry import metrics, trace
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.instrumentation.flask import FlaskInstrumentor
    2. Depois da declaração do método format() (linha 9), insira o seguinte código (observe a indentação):
              span = trace.get_current_span()
    3. Depois da linha 13 (que contém "message": record.getMessage()), insira o seguinte código (observe o recuo):
                  "logging.googleapis.com/trace": google_trace_id_format(span.get_span_context().trace_id),
            "logging.googleapis.com/spanId": trace.format_span_id(span.get_span_context().span_id),
      Esses dois atributos adicionais ajudam a correlacionar os registros de aplicativos e os períodos de rastreamento do OTel.
    4. Depois da linha app = Flask(__name__) (linha 31), insira o seguinte código:
      FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()
      Essa linha instrumenta todas as solicitações de entrada e saída do nosso aplicativo flask com rastreamento.
    5. Logo após o novo código adicionado (após a linha 33), adicione o seguinte código:
      meter = metrics.get_meter(__name__)
requests_counter = meter.create_counter(
    name="model_call_counter",
    description="number of model invocations",
    unit="1"
)
      Essas linhas criam uma nova métrica do tipo contador com o nome model_call_counter e a registram para exportação.
    6. Depois da chamada para logger.debug() (linha 49), insira o seguinte código:
          requests_counter.add(1, {'animal': animal})
      Essa mudança vai incrementar o contador em 1 toda vez que o aplicativo chamar a API Vertex para interagir com o modelo Gemini.

Implantar o código do aplicativo de IA generativa no Cloud Run

  1. Na janela do terminal, execute o comando para implantar o código-fonte do aplicativo no Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    Se você receber uma mensagem como a abaixo, o comando vai criar um novo repositório. Clique em Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    O processo de implantação pode levar alguns minutos. Depois que o processo de implantação for concluído, você vai receber uma saída como esta:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. Copie o URL do serviço do Cloud Run exibido para uma guia ou janela separada no navegador. Como alternativa, execute o comando a seguir no terminal para imprimir o URL do serviço e clique no URL mostrado enquanto pressiona a tecla Ctrl para abrir o URL:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    Quando o URL é aberto, você pode receber um erro 500 ou a mensagem:
    Sorry, this is just a placeholder...
    Isso significa que os serviços não concluíram a implantação. Aguarde alguns instantes e atualize a página. No final, você vai encontrar um texto que começa com Curiosidades sobre cães e contém 10 curiosidades sobre cães.

Para gerar dados de telemetria, abra o URL do serviço. Atualize a página enquanto muda o valor do parâmetro ?animal= para obter resultados diferentes.

Analisar rastros de aplicativos

  1. Clique no botão abaixo para abrir a página do explorador de traces no console do Cloud:

  2. Selecione um dos rastros mais recentes. Você deve ver cinco ou seis spans que se parecem com a captura de tela abaixo.
    Visualização do período do app no explorador de Trace
  3. Encontre o período que rastreia a chamada para o manipulador de eventos (o método fun_facts). Será o último trecho com o nome /.
  4. No painel Detalhes do trace, selecione Registros e eventos. Você vai encontrar registros de aplicativos que se correlacionam a esse período específico. A correlação é detectada usando os IDs de trace e de período no trace e no registro. Você vai encontrar o registro do aplicativo que gravou a solicitação e a resposta da API Vertex.

Conhecer a métrica de contador

  1. Clique no botão abaixo para abrir a página do Metrics Explorer no console do Cloud:

  2. Na barra de ferramentas do painel do criador de consultas, selecione o botão < > MQL ou < > PromQL. Confira a imagem abaixo para ver a localização do botão.
    Local do botão MQL no Metrics Explorer
  3. Verifique se PromQL está selecionado no botão de alternância Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.
  4. Insira sua consulta no editor Consultas:
    sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))
  5. Clique em Executar consulta.Quando a opção Execução automática está ativada, o botão Executar consulta não é mostrado.

11. (Opcional) Informações sensíveis ofuscadas dos registros

Na etapa 10, registramos informações sobre a interação do aplicativo com o modelo Gemini. Essas informações incluíam o nome do animal, o comando e a resposta do modelo. Embora o armazenamento dessas informações no registro seja seguro, isso não é necessário para muitos outros cenários. A solicitação pode incluir informações pessoais ou sensíveis que o usuário não quer que sejam armazenadas. Para resolver isso, você pode ofuscar os dados sensíveis gravados no Cloud Logging. Para minimizar as modificações no código, recomendamos a solução abaixo.

  1. Criar um tópico do Pub/Sub para armazenar entradas de registro recebidas
  2. Crie um coletor de registros que redirecione os registros ingeridos para o tópico do Pub/Sub.
  3. Crie um pipeline do Dataflow que modifique os registros redirecionados para o tópico do Pub/Sub seguindo estas etapas:
    1. Ler uma entrada de registro do tópico do PubSub
    2. Inspecione o payload da entrada em busca de informações sensíveis usando a API de inspeção de DLP.
    3. Edite as informações sensíveis no payload usando um dos métodos de edição da DLP.
    4. Gravar a entrada de registro ofuscada no Cloud Logging
  4. Implante o pipeline.

12. (Opcional) Limpar

Para evitar cobranças por recursos e APIs usados no codelab, é recomendável limpar o ambiente após o término do laboratório. A maneira mais fácil de evitar cobranças é excluindo o projeto criado para o codelab.

  1. Para excluir o projeto, execute o comando "delete project" no terminal:
    PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete ${PROJECT_ID} --quiet
    A exclusão do projeto do Cloud interrompe o faturamento de todos os recursos e APIs usados nele. Você vai receber esta mensagem, em que PROJECT_ID será o ID do projeto:
    Deleted [https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID].

You can undo this operation for a limited period by running the command below.
    $ gcloud projects undelete PROJECT_ID

See https://cloud.google.com/resource-manager/docs/creating-managing-projects for information on shutting down projects.
  2. (Opcional) Se você receber um erro, consulte a etapa 5 para encontrar o ID do projeto que você usou durante o laboratório. Substitua-o pelo comando na primeira instrução. Por exemplo, se o ID do projeto for lab-example-project, o comando será:
    gcloud projects delete lab-project-id-example --quiet

13. Parabéns

Neste laboratório, você criou um aplicativo de IA generativa que usa o modelo Gemini para fazer previsões. E instrumentou o aplicativo com recursos essenciais de monitoramento e geração de registros. Você implantou o aplicativo e fez alterações do código-fonte para o Cloud Run. Em seguida, use os produtos do Google Cloud Observability para acompanhar a performance do aplicativo e garantir a confiabilidade dele.

Se você tem interesse em participar de um estudo de pesquisa de experiência do usuário (UX) para melhorar os produtos com que trabalha hoje, faça sua inscrição aqui.

Confira algumas opções para continuar aprendendo: