De Zero a Vertex AI Invoke Gemini utilizando Princípios de IA Responsável
Este artigo é um tutorial sobre como implantar uma aplicação FastAPI no Google Cloud Run que invoca modelos Gemini através do Vertex AI, enquanto implementa princípios de IA responsável.
Introdução
O guia demonstra como configurar filtros de segurança para quatro categorias de danos: conteúdo perigoso, assédio, discurso de ódio e conteúdo sexualmente explícito, com limites de bloqueio rigorosos. Utiliza o Vellox como um adaptador para executar aplicações ASGI no Google Cloud Functions, implementa autenticação por token Bearer para segurança, e percorre todo o processo de configuração, incluindo a ativação dos serviços do Google Cloud necessários, configuração de funções IAM e implantação da função com variáveis de ambiente.
O tutorial enfatiza implementações práticas de segurança ao mostrar como o Vertex AI filtra tanto as entradas quanto as saídas, retornando um motivo de “SAFETY” com classificações detalhadas de segurança quando conteúdo prejudicial é detectado. Isso o torna particularmente útil para desenvolvedores que desejam construir aplicações de IA com moderação de conteúdo e segurança integradas desde o início.
Tecnologia Utilizada
Funções do Cloud Run:
- Responda rapidamente a eventos ou gatilhos HTTP.
- Deseja configuração mínima — toda a infraestrutura é gerenciada para você.
- Está trabalhando com funções concisas em vez de serviços completos.
Vellox:
O Vellox é um adaptador para executar aplicações ASGI (Interface de Gateway de Servidor Assíncrono) nas Funções do GCP Cloud.
HTTPBearer:
O HTTPBearer no FastAPI é uma utilidade de segurança fornecida pelo módulo fastapi.security. É projetado para lidar com autenticação por token Bearer, que é um método comum para proteger pontos finais de API.
Passos
Configuração do Ambiente de Desenvolvimento
Use devcontainer para instalar tudo. Configure o Docker e o DevContainer e, após puxar o código, você estará pronto para começar.
Ativar Serviços
Na primeira vez que você trabalhar com o seguinte comando:
gcloud initem seguida:
gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com run.googleapis.com logging.googleapis.com aiplatform.googleapis.comPermissões IAM
Na IAM, conceda o papel de projeto ‘roles/aiplatform.user’ ao projeto atual.
Implantação com Variáveis de Ambiente
Utilize o seguinte comando:
gcloud run deploy fastapi-func --source . --function handler --base-image python313 --region asia-south1 --set-env-vars API_TOKEN="damn-long-token",GOOGLE_GENAI_USE_VERTEXAI=True,GOOGLE_CLOUD_LOCATION=global --allow-unauthenticatedEste comando:
- Implanta uma função FastAPI chamada handler da sua pasta local.
- Executa no Python 3.13, na região de Mumbai (asia-south1).
- Tem variáveis de ambiente definidas para tokens de API e uso do Google Vertex AI.
- Está disponível publicamente (sem necessidade de autenticação, exceto o que configuramos para Bearer).
Visão Geral do main.py
O exemplo GCP FastAPI com Google Gemini AI (com Filtros de Conteúdo de Segurança) é apresentado no código a seguir:
import httpx, os, uuid
from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from vellox import Vellox
from pydantic import BaseModel
from typing import Optional
from google import genai
from google.genai.types import (
GenerateContentConfig,
HarmCategory,
HarmBlockThreshold,
SafetySetting,
)
safety_settings = [
SafetySetting(category=HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT, threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE),
SafetySetting(category=HarmCategory.HARM_CATEGORY_HARASSMENT, threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE),
SafetySetting(category=HarmCategory.HARM_CATEGORY_HATE_SPEECH, threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE),
SafetySetting(category=HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT, threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE),
]
app = FastAPI()
_security = HTTPBearer(auto_error=False)
API_TOKEN = os.getenv("API_TOKEN", "")
client = genai.Client()
MODEL = os.getenv("GEMINI_MODEL", "gemini-2.5-flash")
class SummarizeTextRequest(BaseModel):
text: Optional[str] = None
def require_token(creds: HTTPAuthorizationCredentials = Depends(_security)):
if not creds or creds.scheme.lower() != "bearer" or creds.credentials != API_TOKEN:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Token inválido ou ausente.")
@app.get("/health", dependencies=[Depends(require_token)])
def health():
return {"message": "Olá, funcionando (com segurança)!"}
@app.post("/summarize", dependencies=[Depends(require_token)])
async def summarize(req: SummarizeTextRequest):
if not req.text:
raise HTTPException(400, "Forneça 'text'.")
source = req.text
prompt = (""" Resuma em um parágrafo claramente como markdown nn---n""" + source)
resp = client.models.generate_content(model=MODEL, contents=prompt, config=GenerateContentConfig(safety_settings=safety_settings))
if(resp.text is None):
return({"summary": resp.candidates[0]})
return {"summary": resp.text}
vellox = Vellox(app=app, lifespan="off")
def handler(request):
return vellox(request)
Essencialmente, você define safety_settings como uma lista de objetos SafetySetting — cada um declara uma categoria de dano e um limite de bloqueio. Essas categorias/limites são os mesmos documentados para a API Gemini; categorias não listadas retornam aos padrões.
Na prática, essas configurações filtram tanto as entradas quanto as saídas. Se o modelo julgar que o conteúdo atende/excede o limite, a chamada é bloqueada (nenhum texto retornado). Por padrão, o Gemini utiliza um método de bloqueio de danos consciente da severidade no Vertex AI; você pode ajustar esse comportamento conforme necessário.
Para mais informações, acesse o repositório no GitHub.
