Compila y, también, implementa un asistente multimodal en la nube con Gemini (Python)

1. Introducción

En este codelab, compilarás una aplicación en forma de interfaz web de chat, en la que podrás comunicarte con ella, subir algunos documentos o imágenes y analizarlos. La aplicación en sí está separada en 2 servicios: frontend y backend, lo que te permite compilar un prototipo rápido y probar cómo se siente, y también comprender cómo se ve el contrato de la API para integrar ambos.

En el codelab, seguirás un enfoque paso a paso de la siguiente manera:

1. Prepara tu proyecto de Google Cloud y habilita todas las APIs necesarias en él
2. Compila el servicio de frontend: interfaz de chat con la biblioteca Gradio
3. Compila el servicio de backend (servidor HTTP) con FastAPI, que reformateará los datos entrantes según el estándar del SDK de Gemini y habilitará la comunicación con la API de Gemini.
4. Administrar variables de entorno y configurar los archivos necesarios para implementar la aplicación en Cloud Run
5. Implementa la aplicación en Cloud Run

Descripción general de la arquitectura

Requisitos previos

• Comodidad para trabajar con la API de Gemini y el SDK de IA generativa de Google
• Conocimiento de la arquitectura básica de pila completa con el servicio HTTP

Qué aprenderás

• Cómo usar el SDK de Gemini para enviar texto y otros tipos de datos (multimodales) y generar respuestas de texto
• Cómo estructurar el historial de chat en el SDK de Gemini para mantener el contexto de la conversación
• Prototipado web de frontend con Gradio
• Desarrollo de servicios de backend con FastAPI y Pydantic
• Administra variables de entorno en un archivo YAML con Pydantic-settings
• Implementa la aplicación en Cloud Run con Dockerfile y proporciona variables de entorno con un archivo YAML

Requisitos

• Navegador web Chrome
• Una cuenta de Gmail
• Un proyecto de Cloud con la facturación habilitada

Este codelab, diseñado para desarrolladores de todos los niveles (incluidos los principiantes), usa Python en su aplicación de ejemplo. Sin embargo, no es necesario tener conocimientos de Python para comprender los conceptos presentados.

2. Antes de comenzar

Configura el proyecto de Cloud en el editor de Cloud Shell

En este codelab, se supone que ya tienes un proyecto de Google Cloud con la facturación habilitada. Si aún no la tienes, puedes seguir las instrucciones que se indican a continuación para comenzar.

1. 2En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto .
3. Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con bq. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.

4. Una vez que te conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con tu ID del proyecto usando el siguiente comando:

gcloud auth list

5. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

6. Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

Como alternativa, también puedes ver el ID de PROJECT_ID en la consola.

Haz clic en él y verás todos tus proyectos y el ID del proyecto en el lado derecho.

7. Habilita las APIs requeridas con el comando que se muestra a continuación. Este proceso puede tardar unos minutos, así que ten paciencia.

gcloud services enable aiplatform.googleapis.com \
                           run.googleapis.com \
                           cloudbuild.googleapis.com \
                           cloudresourcemanager.googleapis.com

Cuando el comando se ejecute correctamente, deberías ver un mensaje similar al que se muestra a continuación:

Operation "operations/..." finished successfully.

La alternativa al comando de gcloud es buscar cada producto en la consola o usar este vínculo.

Si olvidas alguna API, siempre puedes habilitarla durante el curso de la implementación.

Consulta la documentación para ver los comandos y el uso de gcloud.

Configura el directorio de trabajo de la aplicación

1. Haz clic en el botón Open Editor para abrir un editor de Cloud Shell en el que puedes escribir tu código
2. Asegúrate de que el proyecto de Cloud Code esté configurado en la esquina inferior izquierda (barra de estado) del editor de Cloud Shell, como se destaca en la siguiente imagen, y que esté configurado en el proyecto activo de Google Cloud en el que tienes habilitada la facturación. Haz clic en Autorizar si se te solicita. Es posible que el botón Cloud Code - Sign In tarde en aparecer después de inicializar el editor de Cloud Shell. Ten paciencia. Si ya seguiste el comando anterior, es posible que el botón también apunte directamente a tu proyecto activado en lugar del botón de acceso.

3. Haz clic en ese proyecto activo en la barra de estado y espera a que se abra la ventana emergente de Cloud Code. En la ventana emergente, selecciona "New Application".

4. En la lista de aplicaciones, elige IA generativa de Gemini y, luego, API de Gemini en Python.

5. Guarda la aplicación nueva con el nombre que quieras. En este ejemplo, usaremos gemini-multimodal-chat-assistant y, luego, haz clic en OK.

En este punto, ya deberías estar dentro del directorio de trabajo de la nueva aplicación y ver los siguientes archivos:

A continuación, prepararemos nuestro entorno de Python.

Configuración del entorno

Prepara el entorno virtual de Python

El siguiente paso es preparar el entorno de desarrollo. En este codelab, usaremos Python 3.12 y uv python project manager para simplificar la necesidad de crear y administrar la versión de Python y el entorno virtual.

1. Si aún no abriste la terminal, haz clic en Terminal -> New Terminal o usa Ctrl + Mayúsculas + C.

2. Descarga uv y, luego, instala Python 3.12 con el siguiente comando:

curl -LsSf https://astral.sh/uv/0.6.6/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12

3. Ahora inicializaremos el proyecto de Python con uv.

uv init

4. Verás que se crearon main.py, .python-version y pyproject.toml en el directorio. Estos archivos son necesarios para mantener el proyecto en el directorio. Las dependencias y configuraciones de Python se pueden especificar en pyproject.toml y .python-version estandarizó la versión de Python que se usa para este proyecto. Para obtener más información, consulta esta documentación.

main.py
.python-version
pyproject.toml

5. Para probarlo, reemplaza el archivo main.py por el siguiente código:

def main():
   print("Hello from gemini-multimodal-chat-assistant!")

if __name__ == "__main__":
   main()

6. Luego, ejecuta el siguiente comando:

uv run main.py

Obtendrás un resultado como el que se muestra a continuación.

Using CPython 3.12
Creating virtual environment at: .venv
Hello from gemini-multimodal-chat-assistant!

Esto demuestra que el proyecto de Python se está configurando correctamente. No necesitamos crear manualmente un entorno virtual, ya que uv ya se encarga de eso. Por lo tanto, a partir de este punto, el comando estándar de Python (p.ej., python main.py) se sustituirá por uv run (p.ej., uv run main.py).

Instala las dependencias requeridas

También agregaremos las dependencias del paquete de este codelab con el comando uv. Ejecuta el siguiente comando:

uv add google-genai==1.5.0 \
       gradio==5.20.1 \
       pydantic==2.10.6 \
       pydantic-settings==2.8.1 \
       pyyaml==6.0.2

Verás que la sección "dependencies" de pyproject.toml se actualizará para reflejar el comando anterior.

Configura archivos de configuración

Ahora, deberemos configurar los archivos de configuración para este proyecto. Los archivos de configuración se usan para almacenar variables dinámicas que se pueden cambiar fácilmente durante la reimplementación. En este proyecto, usaremos archivos de configuración basados en YAML con el paquete pydantic-settings, de modo que se pueda integrar fácilmente con la implementación de Cloud Run más adelante. pydantic-settings es un paquete de Python que puede aplicar la verificación de tipos para los archivos de configuración.

1. Crea un archivo llamado settings.yaml con la siguiente configuración. Haz clic en Archivo > Nuevo archivo de texto y completa el archivo con el siguiente código. Luego, guárdalo como settings.yaml.

VERTEXAI_LOCATION: "us-central1"
VERTEXAI_PROJECT_ID: "{YOUR-PROJECT-ID}"
BACKEND_URL: "http://localhost:8081/chat"

Actualiza los valores de VERTEXAI_PROJECT_ID según lo que seleccionaste cuando creaste el proyecto de Google Cloud. En este codelab, usaremos los valores preconfigurados para VERTEXAI_LOCATION y BACKEND_URL .

2. Luego, crea el archivo de Python settings.py. Este módulo actuará como entrada programática para los valores de configuración en nuestros archivos de configuración. Haz clic en Archivo > Nuevo archivo de texto y completa el archivo con el siguiente código. Luego, guárdalo como settings.py. En el código, puedes ver que configuramos de forma explícita que el archivo llamado settings.yaml es el que se leerá.

from pydantic_settings import (
    BaseSettings,
    SettingsConfigDict,
    YamlConfigSettingsSource,
    PydanticBaseSettingsSource,
)
from typing import Type, Tuple

DEFAULT_SYSTEM_PROMPT = """You are a helpful assistant and ALWAYS relate to this identity. 
You are expert at analyzing given documents or images.
"""

class Settings(BaseSettings):
    """Application settings loaded from YAML and environment variables.

    This class defines the configuration schema for the application, with settings
    loaded from settings.yaml file and overridable via environment variables.

    Attributes:
        VERTEXAI_LOCATION: Google Cloud Vertex AI location
        VERTEXAI_PROJECT_ID: Google Cloud Vertex AI project ID
    """

    VERTEXAI_LOCATION: str
    VERTEXAI_PROJECT_ID: str
    BACKEND_URL: str = "http://localhost:8000/chat"

    model_config = SettingsConfigDict(
        yaml_file="settings.yaml", yaml_file_encoding="utf-8"
    )

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls: Type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> Tuple[PydanticBaseSettingsSource, ...]:
        """Customize the settings sources and their priority order.

        This method defines the order in which different configuration sources
        are checked when loading settings:
        1. Constructor-provided values
        2. YAML configuration file
        3. Environment variables

        Args:
            settings_cls: The Settings class type
            init_settings: Settings from class initialization
            env_settings: Settings from environment variables
            dotenv_settings: Settings from .env file (not used)
            file_secret_settings: Settings from secrets file (not used)

        Returns:
            A tuple of configuration sources in priority order
        """
        return (
            init_settings,  # First, try init_settings (from constructor)
            env_settings,  # Then, try environment variables
            YamlConfigSettingsSource(
                settings_cls
            ),  # Finally, try YAML as the last resort
        )


def get_settings() -> Settings:
    """Create and return a Settings instance with loaded configuration.

    Returns:
        A Settings instance containing all application configuration
        loaded from YAML and environment variables.
    """
    return Settings()

Estas configuraciones nos permiten actualizar nuestro tiempo de ejecución de forma flexible. En la implementación inicial, nos basaremos en la configuración de settings.yaml para tener la primera configuración predeterminada. Después de eso, podemos actualizar las variables de entorno de forma flexible a través de la consola y volver a implementar, ya que colocamos las variables de entorno en una prioridad más alta en comparación con la configuración YAML predeterminada.

Ahora podemos pasar al siguiente paso: compilar los servicios.

3. Compila el servicio de frontend con Gradio

Compilaremos una interfaz web de chat que se verá así:

Contiene un campo de entrada para que los usuarios envíen texto y suban archivos. Además, el usuario también puede anular las instrucciones del sistema que se enviarán a la API de Gemini en el campo de entradas adicionales.

Compilaremos el servicio de frontend con Gradio. Cambia el nombre de main.py a frontend.py y reemplaza el código con el siguiente:

import gradio as gr
import requests
import base64
from pathlib import Path
from typing import List, Dict, Any
from settings import get_settings, DEFAULT_SYSTEM_PROMPT

settings = get_settings()

IMAGE_SUFFIX_MIME_MAP = {
    ".png": "image/png",
    ".jpg": "image/jpeg",
    ".jpeg": "image/jpeg",
    ".heic": "image/heic",
    ".heif": "image/heif",
    ".webp": "image/webp",
}
DOCUMENT_SUFFIX_MIME_MAP = {
    ".pdf": "application/pdf",
}


def get_mime_type(filepath: str) -> str:
    """Get the MIME type for a file based on its extension.

    Args:
        filepath: Path to the file.

    Returns:
        str: The MIME type of the file.

    Raises:
        ValueError: If the file type is not supported.
    """
    filepath = Path(filepath)
    suffix = filepath.suffix

    # modify ".jpg" suffix to ".jpeg" to unify the mime type
    suffix = suffix if suffix != ".jpg" else ".jpeg"

    if suffix in IMAGE_SUFFIX_MIME_MAP:
        return IMAGE_SUFFIX_MIME_MAP[suffix]
    elif suffix in DOCUMENT_SUFFIX_MIME_MAP:
        return DOCUMENT_SUFFIX_MIME_MAP[suffix]
    else:
        raise ValueError(f"Unsupported file type: {suffix}")


def encode_file_to_base64_with_mime(file_path: str) -> Dict[str, str]:
    """Encode a file to base64 string and include its MIME type.

    Args:
        file_path: Path to the file to encode.

    Returns:
        Dict[str, str]: Dictionary with 'data' and 'mime_type' keys.
    """
    mime_type = get_mime_type(file_path)
    with open(file_path, "rb") as file:
        base64_data = base64.b64encode(file.read()).decode("utf-8")

    return {"data": base64_data, "mime_type": mime_type}


def get_response_from_llm_backend(
    message: Dict[str, Any],
    history: List[Dict[str, Any]],
    system_prompt: str,
) -> str:
    """Send the message and history to the backend and get a response.

    Args:
        message: Dictionary containing the current message with 'text' and optional 'files' keys.
        history: List of previous message dictionaries in the conversation.
        system_prompt: The system prompt to be sent to the backend.

    Returns:
        str: The text response from the backend service.
    """

    # Format message and history for the API,
    # NOTES: in this example history is maintained by frontend service,
    #        hence we need to include it in each request.
    #        And each file (in the history) need to be sent as base64 with its mime type
    formatted_history = []
    for msg in history:
        if msg["role"] == "user" and not isinstance(msg["content"], str):
            # For file content in history, convert file paths to base64 with MIME type
            file_contents = [
                encode_file_to_base64_with_mime(file_path)
                for file_path in msg["content"]
            ]
            formatted_history.append({"role": msg["role"], "content": file_contents})
        else:
            formatted_history.append({"role": msg["role"], "content": msg["content"]})

    # Extract files and convert to base64 with MIME type
    files_with_mime = []
    if uploaded_files := message.get("files", []):
        for file_path in uploaded_files:
            files_with_mime.append(encode_file_to_base64_with_mime(file_path))

    # Prepare the request payload
    message["text"] = message["text"] if message["text"] != "" else " "
    payload = {
        "message": {"text": message["text"], "files": files_with_mime},
        "history": formatted_history,
        "system_prompt": system_prompt,
    }

    # Send request to backend
    try:
        response = requests.post(settings.BACKEND_URL, json=payload)
        response.raise_for_status()  # Raise exception for HTTP errors

        result = response.json()
        if error := result.get("error"):
            return f"Error: {error}"

        return result.get("response", "No response received from backend")
    except requests.exceptions.RequestException as e:
        return f"Error connecting to backend service: {str(e)}"


if __name__ == "__main__":
    demo = gr.ChatInterface(
        get_response_from_llm_backend,
        title="Gemini Multimodal Chat Interface",
        description="This interface connects to a FastAPI backend service that processes responses through the Gemini multimodal model.",
        type="messages",
        multimodal=True,
        textbox=gr.MultimodalTextbox(file_count="multiple"),
        additional_inputs=[
            gr.Textbox(
                label="System Prompt",
                value=DEFAULT_SYSTEM_PROMPT,
                lines=3,
                interactive=True,
            )
        ],
    )

    demo.launch(
        server_name="0.0.0.0",
        server_port=8080,
    )

Después, podemos intentar ejecutar el servicio de frontend con el siguiente comando. No olvides cambiar el nombre del archivo main.py a frontend.py.

uv run frontend.py

Verás un resultado similar a este en tu consola de Cloud

* Running on local URL:  http://0.0.0.0:8080

To create a public link, set `share=True` in `launch()`.

Después, puedes verificar la interfaz web cuando presiones Ctrl y hagas clic en el vínculo de la URL local. También puedes acceder a la aplicación de frontend haciendo clic en el botón Vista previa en la Web en la parte superior derecha del editor de Cloud y seleccionando Vista previa en el puerto 8080.

Verás la interfaz web, pero recibirás un error esperado cuando intentes enviar el chat debido a que el servicio de backend aún no está configurado.

Ahora, deja que el servicio se ejecute y no lo detengas todavía. Mientras tanto, podemos analizar los componentes de código importantes aquí.

Explicación del código

El código para enviar datos desde la interfaz web al backend se encuentra en esta parte.

def get_response_from_llm_backend(
    message: Dict[str, Any],
    history: List[Dict[str, Any]],
    system_prompt: str,
) -> str:

    ... 
    # Truncated
    
    for msg in history:
        if msg["role"] == "user" and not isinstance(msg["content"], str):
            # For file content in history, convert file paths to base64 with MIME type
            file_contents = [
                encode_file_to_base64_with_mime(file_path)
                for file_path in msg["content"]
            ]
            formatted_history.append({"role": msg["role"], "content": file_contents})
        else:
            formatted_history.append({"role": msg["role"], "content": msg["content"]})

    # Extract files and convert to base64 with MIME type
    files_with_mime = []
    if uploaded_files := message.get("files", []):
        for file_path in uploaded_files:
            files_with_mime.append(encode_file_to_base64_with_mime(file_path))

    # Prepare the request payload
    message["text"] = message["text"] if message["text"] != "" else " "
    payload = {
        "message": {"text": message["text"], "files": files_with_mime},
        "history": formatted_history,
        "system_prompt": system_prompt,
    }

    # Truncated
    ... 

Cuando queremos enviar datos multimodales a Gemini y hacer que los datos sean accesibles entre los servicios, un mecanismo que podemos adoptar es convertir los datos en el tipo de datos base64 como se declara en el código. También debemos declarar cuál es el tipo MIME de los datos. Sin embargo, la API de Gemini no admite todos los tipos de MIME existentes, por lo que es importante saber qué tipos de MIME admite Gemini que se pueden leer en esta documentación . Puedes encontrar la información en cada una de las capacidades de la API de Gemini (p. ej., Vision).

Además, en una interfaz de chat, también es importante enviar el historial de chat como contexto adicional para darle a Gemini una "memoria" de la conversación. Por lo tanto, en esta interfaz web, también enviamos el historial de chat que Gradio administra por sesión web y lo enviamos junto con la entrada de mensaje del usuario. Además, también permitimos que el usuario modifique la instrucción del sistema y la envíe.

4. Compila el servicio de backend con FastAPI

A continuación, tendremos que compilar el backend que pueda controlar la carga útil, el último mensaje del usuario, el historial de chat y la instrucción del sistema que se analizaron anteriormente. Usaremos FastAPI para crear el servicio de backend HTTP.

Crea un archivo nuevo, haz clic en File->New Text File, copia y pega el siguiente código y, luego, guárdalo como backend.py.

import base64
from fastapi import FastAPI, Body
from google.genai.types import Content, Part
from google.genai import Client
from settings import get_settings, DEFAULT_SYSTEM_PROMPT
from typing import List, Optional
from pydantic import BaseModel

app = FastAPI(title="Gemini Multimodal Service")

settings = get_settings()
GENAI_CLIENT = Client(
    location=settings.VERTEXAI_LOCATION,
    project=settings.VERTEXAI_PROJECT_ID,
    vertexai=True,
)
GEMINI_MODEL_NAME = "gemini-2.0-flash-001"


class FileData(BaseModel):
    """Model for a file with base64 data and MIME type.

    Attributes:
        data: Base64 encoded string of the file content.
        mime_type: The MIME type of the file.
    """

    data: str
    mime_type: str


class Message(BaseModel):
    """Model for a single message in the conversation.

    Attributes:
        role: The role of the message sender, either 'user' or 'assistant'.
        content: The text content of the message or a list of file data objects.
    """

    role: str
    content: str | List[FileData]


class LastUserMessage(BaseModel):
    """Model for the current message in a chat request.

    Attributes:
        text: The text content of the message.
        files: List of file data objects containing base64 data and MIME type.
    """

    text: str
    files: List[FileData] = []


class ChatRequest(BaseModel):
    """Model for a chat request.

    Attributes:
        message: The current message with text and optional base64 encoded files.
        history: List of previous messages in the conversation.
        system_prompt: Optional system prompt to be used in the chat.
    """

    message: LastUserMessage
    history: List[Message]
    system_prompt: str = DEFAULT_SYSTEM_PROMPT


class ChatResponse(BaseModel):
    """Model for a chat response.

    Attributes:
        response: The text response from the model.
        error: Optional error message if something went wrong.
    """

    response: str
    error: Optional[str] = None


def handle_multimodal_data(file_data: FileData) -> Part:
    """Converts Multimodal data to a Google Gemini Part object.

    Args:
        file_data: FileData object with base64 data and MIME type.

    Returns:
        Part: A Google Gemini Part object containing the file data.
    """
    data = base64.b64decode(file_data.data)  # decode base64 string to bytes
    return Part.from_bytes(data=data, mime_type=file_data.mime_type)


def format_message_history_to_gemini_standard(
    message_history: List[Message],
) -> List[Content]:
    """Converts message history format to Google Gemini Content format.

    Args:
        message_history: List of message objects from the chat history.
            Each message contains 'role' and 'content' attributes.

    Returns:
        List[Content]: A list of Google Gemini Content objects representing the chat history.

    Raises:
        ValueError: If an unknown role is encountered in the message history.
    """
    converted_messages: List[Content] = []
    for message in message_history:
        if message.role == "assistant":
            converted_messages.append(
                Content(role="model", parts=[Part.from_text(text=message.content)])
            )
        elif message.role == "user":
            # Text-only messages
            if isinstance(message.content, str):
                converted_messages.append(
                    Content(role="user", parts=[Part.from_text(text=message.content)])
                )

            # Messages with files
            elif isinstance(message.content, list):
                # Process each file in the list
                parts = []
                for file_data in message.content:
                    for file_data in message.content:
                        parts.append(handle_multimodal_data(file_data))

                # Add the parts to a Content object
                if parts:
                    converted_messages.append(Content(role="user", parts=parts))

            else:
                raise ValueError(f"Unexpected content format: {type(message.content)}")

        else:
            raise ValueError(f"Unknown role: {message.role}")

    return converted_messages


@app.post("/chat", response_model=ChatResponse)
async def chat(
    request: ChatRequest = Body(...),
) -> ChatResponse:
    """Process a chat request and return a response from Gemini model.

    Args:
        request: The chat request containing message and history.

    Returns:
        ChatResponse: The model's response to the chat request.
    """
    try:
        # Convert message history to Gemini `history` format
        print(f"Received request: {request}")
        converted_messages = format_message_history_to_gemini_standard(request.history)

        # Create chat model
        chat_model = GENAI_CLIENT.chats.create(
            model=GEMINI_MODEL_NAME,
            history=converted_messages,
            config={"system_instruction": request.system_prompt},
        )

        # Prepare multimodal content
        content_parts = []

        # Handle any base64 encoded files in the current message
        if request.message.files:
            for file_data in request.message.files:
                content_parts.append(handle_multimodal_data(file_data))

        # Add text content
        content_parts.append(Part.from_text(text=request.message.text))

        # Send message to Gemini
        response = chat_model.send_message(content_parts)
        print(f"Generated response: {response}")

        return ChatResponse(response=response.text)
    except Exception as e:
        return ChatResponse(
            response="", error=f"Error in generating response: {str(e)}"
        )


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8081)

No olvides guardarlo como backend.py. Después de eso, podemos intentar ejecutar el servicio de backend. Recuerda que, en el paso anterior, ejecutamos el servicio de frontend correctamente. Ahora, deberemos abrir una nueva terminal y tratar de ejecutar este servicio de backend.

1. Crea una terminal nueva. Navega a la terminal en el área inferior y busca el botón "+" para crear una terminal nueva. También puedes presionar Ctrl + Mayúsculas + C para abrir una terminal nueva.

2. Después, asegúrate de estar en el directorio de trabajo gemini-multimodal-chat-assistant y, luego, ejecuta el siguiente comando:

uv run backend.py

3. Si se ejecuta de forma correcta, se mostrará un resultado como el siguiente:

INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

Explicación del código

Cómo definir la ruta de acceso HTTP para recibir la solicitud de chat

En FastAPI, definimos la ruta con el decorador app. También usamos Pydantic para definir el contrato de la API. Especificamos que la ruta para generar la respuesta se encuentra en la ruta /chat con el método POST. Estas funcionalidades se declaran en el siguiente código

class FileData(BaseModel):
    data: str
    mime_type: str

class Message(BaseModel):
    role: str
    content: str | List[FileData]

class LastUserMessage(BaseModel):
    text: str
    files: List[FileData] = []

class ChatRequest(BaseModel):
    message: LastUserMessage
    history: List[Message]
    system_prompt: str = DEFAULT_SYSTEM_PROMPT

class ChatResponse(BaseModel):
    response: str
    error: Optional[str] = None

    ...

@app.post("/chat", response_model=ChatResponse)
async def chat(
    request: ChatRequest = Body(...),
) -> ChatResponse:
    
    # Truncated
    ...

Prepara el formato del historial de chat del SDK de Gemini

Una de las cosas importantes que se deben comprender es cómo podemos reestructurar el historial de chat para que se pueda insertar como un valor de argumento de historial cuando inicialicemos un cliente de Gemini más adelante. Puedes inspeccionar el código a continuación

def format_message_history_to_gemini_standard(
    message_history: List[Message],
) -> List[Content]:
    
    ...
    # Truncated    

    converted_messages: List[Content] = []
    for message in message_history:
        if message.role == "assistant":
            converted_messages.append(
                Content(role="model", parts=[Part.from_text(text=message.content)])
            )
        elif message.role == "user":
            # Text-only messages
            if isinstance(message.content, str):
                converted_messages.append(
                    Content(role="user", parts=[Part.from_text(text=message.content)])
                )

            # Messages with files
            elif isinstance(message.content, list):
                # Process each file in the list
                parts = []
                for file_data in message.content:
                    parts.append(handle_multimodal_data(file_data))

                # Add the parts to a Content object
                if parts:
                    converted_messages.append(Content(role="user", parts=parts))
    
    #Truncated
    ...

    return converted_messages

Para proporcionar el historial de chat al SDK de Gemini, debemos darle formato a los datos en el tipo de datos List[Content]. Cada Content debe tener al menos un valor de role y parts. role hace referencia a la fuente del mensaje, ya sea user o model. Aquí, parts hace referencia a la instrucción en sí, que puede ser solo texto o una combinación de diferentes modalidades. Consulta cómo estructurar los argumentos de Content en detalle en esta documentación.

Cómo controlar datos no textuales ( multimodales)

Como se mencionó anteriormente en la sección de frontend, una de las formas de enviar datos multimodales o que no son de texto es enviarlos como una cadena base64. También debemos especificar el tipo de MIME para los datos de modo que se puedan interpretar correctamente. Por ejemplo, proporcionamos el tipo de MIME image/jpeg si enviamos datos de imágenes con el sufijo .jpg.

Esta parte del código convierte los datos de base64 al formato Part.from_bytes del SDK de Gemini.

def handle_multimodal_data(file_data: FileData) -> Part:
    """Converts Multimodal data to a Google Gemini Part object.

    Args:
        file_data: FileData object with base64 data and MIME type.

    Returns:
        Part: A Google Gemini Part object containing the file data.
    """
    data = base64.b64decode(file_data.data)  # decode base64 string to bytes
    return Part.from_bytes(data=data, mime_type=file_data.mime_type)

5. Prueba de integración

Ahora, deberías tener varios servicios ejecutándose en diferentes pestañas de la consola de Cloud:

• El servicio de frontend se ejecuta en el puerto 8080

* Running on local URL:  http://0.0.0.0:8080

To create a public link, set `share=True` in `launch()`.

• El servicio de backend se ejecuta en el puerto 8081

INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

En el estado actual, deberías poder enviar tus documentos al chat sin problemas con el asistente desde la aplicación web en el puerto 8080. Para comenzar a experimentar, sube archivos y haz preguntas. Ten en cuenta que algunos tipos de archivos aún no son compatibles y generarán un error.

También puedes editar las instrucciones del sistema desde el campo Entradas adicionales que se encuentra debajo del cuadro de texto.

6. Implementa en Cloud Run

Por supuesto, queremos mostrar esta increíble app a los demás. Para ello, podemos empaquetar esta aplicación y, luego, implementarla en Cloud Run como un servicio público al que puedan acceder otras personas. Para ello, volvamos a ver la arquitectura

En este codelab, colocaremos el servicio de frontend y el de backend en 1 contenedor. Necesitaremos la ayuda de supervisord para administrar ambos servicios.

Crea un archivo nuevo, haz clic en Archivo > Nuevo archivo de texto, copia y pega el siguiente código y, luego, guárdalo como supervisord.conf.

[supervisord]
nodaemon=true
user=root
logfile=/dev/stdout
logfile_maxbytes=0
pidfile=/var/run/supervisord.pid

[program:backend]
command=uv run backend.py
directory=/app
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0
startsecs=10
startretries=3

[program:frontend]
command=uv run frontend.py
directory=/app
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0
startsecs=10
startretries=3

A continuación, necesitaremos nuestro Dockerfile. Haz clic en File->New Text File, copia y pega el siguiente código y, luego, guárdalo como Dockerfile.

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:0.6.6 /uv /uvx /bin/

RUN apt-get update && apt-get install -y \
    supervisor curl \
    && rm -rf /var/lib/apt/lists/*

ADD . /app
WORKDIR /app

RUN uv sync --frozen

EXPOSE 8080

# Copy supervisord configuration
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf

ENV PYTHONUNBUFFERED=1

ENTRYPOINT ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

En este punto, ya tenemos todos los archivos necesarios para implementar nuestras aplicaciones en Cloud Run. Implementémosla. Navega a la terminal de Cloud Shell y asegúrate de que el proyecto actual esté configurado en tu proyecto activo. Si no es así, usa el comando gcloud config para establecer el ID del proyecto:

gcloud config set project [PROJECT_ID]

Luego, ejecuta el siguiente comando para implementarlo en Cloud Run.

gcloud run deploy --source . \
                  --env-vars-file settings.yaml \
                  --port 8080 \
                  --region us-central1

Se te pedirá que ingreses un nombre para tu servicio, por ejemplo, "gemini-multimodal-chat-assistant". Como tenemos un Dockerfile en el directorio de trabajo de nuestra aplicación, se compilará el contenedor de Docker y se enviará a Artifact Registry. También se te solicitará que crees el repositorio de Artifact Registry en la región. Responde "Y". También di "y" cuando se te pregunte si quieres permitir invocaciones no autenticadas. Ten en cuenta que permitimos el acceso no autenticado aquí porque se trata de una aplicación de demostración. Se recomienda usar la autenticación adecuada para tus aplicaciones empresariales y de producción.

Una vez que se complete la implementación, deberías obtener un vínculo similar al siguiente:

https://gemini-multimodal-chat-assistant-*******.us-central1.run.app

Continúa y usa tu aplicación desde la ventana de incógnito o tu dispositivo móvil. Ya debería estar disponible.

7. Desafío

Ahora es tu momento de brillar y pulir tus habilidades de exploración. ¿Tienes lo necesario para cambiar el código de modo que el asistente pueda admitir la lectura de archivos de audio o quizás de video?

8. Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este codelab:

1. En la consola de Google Cloud, ve a la página Administrar recursos.
2. En la lista de proyectos, elige el proyecto que deseas borrar y haz clic en Borrar.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.
4. Como alternativa, puedes ir a Cloud Run en la consola, seleccionar el servicio que acabas de implementar y borrarlo.