Lección 26 · 10 min · Gratis

Primeros pasos con la compatibilidad de OpenAI

Copyright 2026 Google LLC.

# @title Licensed under the Apache License, Version 2.0 (the "License");
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Este ejemplo ilustra cómo interactuar con la API de Gemini usando la biblioteca de Python de OpenAI.

Este notebook te guiará a través de:

Realizar generación de texto básica usando modelos Gemini a través de la biblioteca de OpenAI
Experimentar con interacciones multimodales, enviando imágenes en tus prompts
Extraer información de texto usando salidas estructuradas (es decir, campos específicos o salida JSON)
Usar herramientas de la API de Gemini, como la llamada a funciones
Generar embeddings usando modelos de la API de Gemini

Más detalles sobre esta compatibilidad con OpenAI en la documentación.

Configuración

Instalar los módulos requeridos

Mientras ejecutas este notebook, necesitarás instalar los siguientes requisitos:

La biblioteca de Python de OpenAI
pdf2image y pdfminer.six (y poppler-utils como su requisito) para manipular archivos PDF

%pip install -U -q openai pillow pdf2image pdfminer.six
!apt -qq -y install poppler-utils # required by pdfminer

Obtén tu clave de API de Gemini

Necesitarás tu clave de API de Gemini para realizar las actividades de este notebook. Puedes generar una nueva en la página Obtener clave de API de AI Studio.

from openai import OpenAI

try:
  # if you are running the notebook on Google Colab
  # and if you have saved your API key in the
  # Colab secrets
  from google.colab import userdata

  GEMINI_API_KEY = userdata.get('GEMINI_API_KEY')

except:
  # enter manually your API key here if you are not using Google Colab
  GEMINI_API_KEY = "--enter-your-API-key-here--"

# OpenAI client
client = OpenAI(
    api_key=GEMINI_API_KEY,
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_8", line 1, in <module>
ModuleNotFoundError: No module named 'openai'

Define el modelo Gemini a usar

Puedes empezar listando los modelos disponibles usando la biblioteca de OpenAI.

models = client.models.list()
for model in models:
  if 'gemini-2' in model.id:
    print(model.id)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_10", line 1, in <module>
NameError: name 'client' is not defined

Define el modelo Gemini a usar

En este ejemplo, usarás el modelo gemini-3.7-flash. Para más detalles sobre los modelos disponibles, consulta la página Modelos Gemini de la documentación de la API de Gemini.

MODEL_ID = "gemini-3.7-flash" # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}

Interacción inicial - generar texto

Para tu primera solicitud, usa el SDK de OpenAI para realizar la generación de texto con un prompt de texto.

from IPython.display import Markdown

prompt = "What is generative AI?" # @param

response = client.chat.completions.create(
  model=MODEL_ID,
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {
      "role": "user",
      "content": prompt
    }
  ]
)

Markdown(response.choices[0].message.content)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_14", line 5, in <module>
NameError: name 'client' is not defined

Generando código

Puedes trabajar con la API de Gemini para que genere código por ti.

prompt = """
    Write a C program that takes two IP addresses, representing the start and end of a range
    (e.g., 192.168.1.1 and 192.168.1.254), as input arguments. The program should convert this
    IP address range into the minimal set of CIDR notations that completely cover the given
    range. The output should be a comma-separated list of CIDR blocks.
"""

response = client.chat.completions.create(
    model=MODEL_ID,
    messages=[
        {
            "role": "user",
            "content": prompt
        }
    ]
)

Markdown(response.choices[0].message.content)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_16", line 8, in <module>
NameError: name 'client' is not defined

Interacciones multimodales

Los modelos Gemini son capaces de procesar diferentes modalidades de datos, como archivos no estructurados, imágenes, audio y videos, lo que te permite experimentar con escenarios multimodales donde puedes pedirle al modelo que describa, explique, obtenga información o extraiga información de esos datos multimedia incluidos en tus prompts. En esta sección trabajarás en diferentes escenarios con información multimedia.

IMPORTANTE: La compatibilidad del SDK de OpenAI solo admite imágenes y archivos de audio en línea. Para soporte de videos, usa el SDK de Python de la API de Gemini.

Trabajando con imágenes (una sola imagen)

Primero descargarás la imagen con la que quieres trabajar.

from PIL import Image as PImage


# define the image you want to download
image_url = "https://storage.googleapis.com/generativeai-downloads/images/Japanese_Bento.png" # @param
image_filename = image_url.split("/")[-1]

# download the image
!wget -q $image_url

# visualize the downloaded image
im = PImage.open(image_filename)
im.thumbnail([620,620], PImage.Resampling.LANCZOS)
im

nt call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_19", line 12, in <module>
  File "/usr/local/google/home/giom/.gemini/jetski/scratch/cookbook-agentB-interactions/.venv/lib/python3.13/site-packages/PIL/Image.py", line 3635, in open
    fp = builtins.open(filename, "rb")
FileNotFoundError: [Errno 2] No such file or directory: 'Japanese_Bento.png'

Ahora puedes codificar la imagen y trabajar con la biblioteca de OpenAI para interactuar con los modelos Gemini.

import base64
import requests


# define a helper function to encode the images in base64 format
def encode_image(image_path):
  image = requests.get(image_path)
  return base64.b64encode(image.content).decode('utf-8')

# Getting the base64 encoding
encoded_image = encode_image(image_url)

response = client.chat.completions.create(
  model=MODEL_ID,
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe the items on this image. If there is any non-English text, translate it as well"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": f"data:image/png;base64,{encoded_image}",
          },
        },
      ],
    }
  ]
)

Markdown(response.choices[0].message.content)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_21", line 13, in <module>
NameError: name 'client' is not defined

Trabajando con imágenes (múltiples imágenes)

Puedes hacer el mismo proceso mientras envías varias imágenes en el mismo prompt.

import matplotlib.pyplot as plt
from IPython.display import display, Image
from matplotlib.pyplot import imread


# define the images you want to download
image_urls = [
    "https://storage.googleapis.com/github-repo/img/gemini/retail-recommendations/furnitures/cesar-couto-OB2F6CsMva8-unsplash.jpg",
    "https://storage.googleapis.com/github-repo/img/gemini/retail-recommendations/furnitures/daniil-silantev-1P6AnKDw6S8-unsplash.jpg",
    "https://storage.googleapis.com/github-repo/img/gemini/retail-recommendations/furnitures/ruslan-bardash-4kTbAMRAHtQ-unsplash.jpg",
    "https://storage.googleapis.com/github-repo/img/gemini/retail-recommendations/furnitures/scopic-ltd-NLlWwR4d3qU-unsplash.jpg",
]

for url in image_urls:
    display(Image(url=url, width=200, height=250))

<IPython.core.display.Image object>
<IPython.core.display.Image object>
<IPython.core.display.Image object>
<IPython.core.display.Image object>

Ahora puedes codificar las imágenes y enviarlas con tu prompt.

import base64
import requests


# define a helper function to encode the images in base64 format
def encode_image(image_path):
  image = requests.get(image_path)
  return base64.b64encode(image.content).decode('utf-8')


# Getting the base64 encoding
encoded_images =[]
for image in image_urls:
  encoded_images.append(encode_image(image))

response = client.chat.completions.create(
  model=MODEL_ID,
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe for what type of living room each of those items are the best match"
        },
        *[{
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}",
                    },
        }
                for image_data in encoded_images]
      ],
    }
  ]
)

Markdown(response.choices[0].message.content)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_25", line 16, in <module>
NameError: name 'client' is not defined

Trabajando con archivos de audio

También puedes enviar archivos de audio en tu prompt. Los datos de audio proporcionan una entrada más rica que el texto solo, y se pueden usar para tareas como la transcripción, o como un prompt directo como un asistente de voz.

Primero necesitas descargar el audio que quieres usar.

from IPython.display import display, Audio


audio_url = "https://storage.googleapis.com/generativeai-downloads/data/Apollo-11_Day-01-Highlights-10s.mp3" # @param
audio_filename = audio_url.split("/")[-1]

# download the audio
!wget -q $audio_url

# listen to the downloaded audio
display(Audio(audio_filename, autoplay=False))

esult = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_27", line 11, in <module>
  File "/usr/local/google/home/giom/.gemini/jetski/scratch/cookbook-agentB-interactions/.venv/lib/python3.13/site-packages/IPython/lib/display.py", line 130, in __init__
    raise ValueError("rate must be specified when data is a numpy array or list of audio samples.")
ValueError: rate must be specified when data is a numpy array or list of audio samples.

Ahora codificarás el audio en base64 y lo enviarás como parte de tu prompt de solicitud.

# define a helper function to encode the images in base64 format
def encode_audio(audio_path):
  with open(audio_path, 'rb') as audio_file:
    audio_content = audio_file.read()
    return base64.b64encode(audio_content).decode('utf-8')

base64_audio = encode_audio(audio_filename)

prompt = "Transcribe this audio file. After transcribing, tell me from what this can be related to." # @param
response = client.chat.completions.create(
    model=MODEL_ID,
    messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": prompt,
        },
        {
              "type": "input_audio",
              "input_audio": {
                "data": base64_audio,
                "format": "mp3"
          }
        }
      ],
    }
  ],
)

Markdown(response.choices[0].message.content)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_29", line 7, in <module>
  File "Get_started_OpenAI_Compatibility.ipynb:cell_29", line 3, in encode_audio
FileNotFoundError: [Errno 2] No such file or directory: 'Apollo-11_Day-01-Highlights-10s.mp3'

Salidas estructuradas

La API de Gemini te permite formatear la forma en que se generará tu respuesta a través de salidas estructuradas. Puedes definir la estructura que quieres usar como un esquema definido y, usando la biblioteca de OpenAI, envías esta estructura como el parámetro response_format.

En este ejemplo, harás lo siguiente:

descargar un artículo científico
extraer su información
definir la estructura en la que quieres tu respuesta
enviar tu solicitud usando el parámetro response_format

Primero necesitas descargar el artículo de referencia. Usarás el artículo de Google Attention is all your need que introdujo la arquitectura Transformers.

from IPython.display import Image
from pdf2image import convert_from_path


# download the PDF file
pdf_url = "https://arxiv.org/pdf/1706.03762.pdf" # @param
pdf_filename = pdf_url.split("/")[-1]
!wget -q $pdf_url

## visualize the pdf as an image
# convert the PDF file to images
images = convert_from_path(pdf_filename, 200)
for image in images:
    image.save('cover.png', "PNG")
    break

# show the pdf first page
Image('cover.png', width=500, height=600)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_31", line 2, in <module>
ModuleNotFoundError: No module named 'pdf2image'

Ahora crearás tu estructura de referencia. Será un Class de Python que se referirá al título, autores, resumen y palabras clave del artículo.

from pydantic import BaseModel


class ResearchPaperExtraction(BaseModel):
    title: str
    authors: list[str]
    abstract: str
    keywords: list[str]

Ahora harás tu solicitud a la API de Gemini enviando el archivo pdf y la estructura de referencia.

import json
from pdfminer.high_level import extract_text


# extract text from the PDF
pdf_text = extract_text(pdf_filename)

prompt = """
    As a specialist in knowledge organization and data refinement, your task is to transform
    raw research paper content into a clearly defined structured format. I will provide you
    with the original, free-form text. Your goal is to parse this text, extract the pertinent
    information, and reconstruct it according to the structure outlined below.
"""

# send your request to the Gemini API
completion = client.beta.chat.completions.parse(
  model=MODEL_ID,
  messages=[
    {"role": "system", "content": prompt},
    {"role": "user", "content": pdf_text}
  ],
  response_format=ResearchPaperExtraction,
)

print(completion.choices[0].message.parsed.model_dump_json(indent=2))

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_35", line 2, in <module>
ModuleNotFoundError: No module named 'pdfminer'

Dada la capacidad de la API de Gemini para manejar salidas estructuradas, también puedes trabajar en escenarios más complejos, como usar la funcionalidad de salida estructurada para ayudarte a generar interfaces de usuario.

Primero defines las clases de Python que representan la estructura que quieres en la salida.

from enum import Enum


class UIType(str, Enum):
    div = "div"
    button = "button"
    header = "header"
    section = "section"
    field = "field"
    form = "form"

class Attribute(BaseModel):
    name: str
    value: str

class UI(BaseModel):
    type: UIType
    label: str
    children: list[str]
    attributes: list[Attribute]

UI.model_rebuild() # This is required to enable recursive types

class Response(BaseModel):
    ui: UI

Ahora envías tu solicitud usando la clase Response como el response_format.

completion = client.beta.chat.completions.parse(
    model=MODEL_ID,
    messages=[
        {"role": "system", "content": "You are a UI generation assistant. Convert the user input into a UI."},
        {"role": "user", "content": "Make a User Profile Form including all required attributes"}
    ],
    response_format=Response,
)

print(completion.choices[0].message.content)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_39", line 1, in <module>
NameError: name 'client' is not defined

Desarrollando con la llamada a funciones de la API de Gemini

La función de llamada a funciones de la API de Gemini te permite extender las capacidades del modelo proporcionando descripciones de funciones o APIs externas.

Para una mayor comprensión de cómo funciona la llamada a funciones con los modelos Gemini, consulta la documentación de la API de Gemini.

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Gets the weather at the user's location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string"},
        },
      },
    },
  }
]

Ahora agregas la estructura tools a tu solicitud.

prompt = """
    What's the weather like in Boston?
"""

completion = client.chat.completions.create(
  model=MODEL_ID,
  messages=[{"role": "user", "content": prompt}],
  tools=tools,
)

print(completion.choices[0].message.tool_calls[0])

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_43", line 5, in <module>
NameError: name 'client' is not defined

Pensamiento

Los modelos Gemini 2.5 y 3 están entrenados para pensar en problemas complejos, lo que lleva a un razonamiento significativamente mejorado. La API de Gemini viene con un parámetro de "presupuesto de pensamiento" que permite un control granular sobre cuánto pensará el modelo.

A diferencia de la API de Gemini, la API de OpenAI ofrece tres niveles de control de pensamiento: "bajo", "medio" y "alto". Aquí está la correspondencia:

Esfuerzo de razonamiento de OpenAI	Presupuesto de pensamiento de Gemini 2.5	Nivel de pensamiento de Gemini 3 Pro
ninguno	0*	N/A
mínimo	1024	bajo
bajo	1024	bajo
medio	8192	alto
alto	24576	alto

Si quieres deshabilitar el pensamiento, puedes establecer el esfuerzo de razonamiento en "ninguno", pero ten en cuenta que el pensamiento no se puede desactivar en los modelos Pro.

prompt = """
    What is 45-78+5x13?
    Double check and explain why your answer is correct.
"""

response = client.chat.completions.create(
  model=MODEL_ID,
  reasoning_effort="low",
  messages=[
      {"role": "system", "content": "You are a helpful assistant."},
      {
        "role": "user",
        "content": prompt
      }
  ]
)

Markdown(response.choices[0].message.content)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_45", line 6, in <module>
NameError: name 'client' is not defined

Predicciones por lotes

Además de las generaciones en tiempo real, la API de Gemini proporciona una capa compatible para realizar generaciones por lotes.

Prepara un archivo JSONL en formato de entrada por lotes de OpenAI. Ten en cuenta que las URL y la estructura general usan la sintaxis de OpenAI, pero los modelos son identificadores de modelos de la API de Gemini.

%%writefile batch_requests.jsonl
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.7-flash", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.7-flash", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
                  ~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "Get_started_OpenAI_Compatibility.ipynb:cell_47", line 1
    %%writefile batch_requests.jsonl
    ^
SyntaxError: invalid syntax

Ahora sube el archivo JSONL con el SDK de GenAI. Hasta que haya soporte para la API de carga de archivos de OpenAI, debes usar el SDK de Google GenAI para subir el archivo y hacer que los datos estén disponibles para la API de Gemini.

%pip install -qU google-genai

# Upload JSONL file in OpenAI batch input format...
from google import genai
from google.genai import types

genai_client = genai.Client(api_key=GEMINI_API_KEY)

uploaded_file = genai_client.files.upload(
    file="batch_requests.jsonl",
    config=types.UploadFileConfig(display_name="my-batch-requests", mime_type="jsonl"),
)
print(f'{uploaded_file.name=}')

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_50", line 5, in <module>
NameError: name 'GOOGLE_API_KEY' is not defined

Crea un trabajo de generación por lotes haciendo referencia al archivo recién subido.

batch = client.batches.create(
    input_file_id=uploaded_file.name,
    endpoint="/v1/chat/completions",
    completion_window="24h"
)
print(f'{batch.id=}')

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_52", line 1, in <module>
NameError: name 'client' is not defined

Los lotes pueden tardar hasta 24 horas en procesarse. Consulta aquí con el siguiente código, o vuelve más tarde y reemplaza batch.id con el ID impreso durante la creación anterior.

import time

while (batch := client.batches.retrieve(batch.id)).status == 'in_progress':
    print(f"Job not finished. Current state: {batch.status}. Waiting 30 seconds...")
    time.sleep(30)

print(f'{batch.status=}')

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_54", line 3, in <module>
NameError: name 'client' is not defined

Ahora que el lote está procesado, descarga los resultados e imprímelos.

if batch.status == 'completed':
    # Download the output file.
    file_content_bytes = genai_client.files.download(file=batch.output_file_id)
    file_content = file_content_bytes.decode('utf-8')

    # Print each output record.
    for i, line in enumerate(file_content.splitlines(), start=1):
            print(i, line)

else:
    print(f'An error occurred. Batch status is "{batch.status}".')

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_56", line 1, in <module>
NameError: name 'batch' is not defined

Generando y trabajando con embeddings

Los embeddings de texto ofrecen una representación comprimida y basada en vectores del texto, típicamente en un espacio de menor dimensión. El principio central es que los textos semánticamente similares tendrán embeddings que son espacialmente próximos dentro del espacio vectorial de embeddings. Esta representación permite soluciones a varios desafíos prevalentes de PNL, incluyendo:

Búsqueda Semántica: Identificar y clasificar textos basándose en la relación semántica.
Recomendación: Sugerir elementos cuyas descripciones textuales exhiben similitud semántica con un texto de entrada dado.
Clasificación: Asignar texto a categorías basándose en la similitud semántica entre el texto y el texto representativo de la categoría.
Agrupación (Clustering): Agrupar textos en clusters basándose en la similitud semántica reflejada en sus respectivos vectores de embedding.
Detección de Valores Atípicos: Identificar textos que son semánticamente disímiles de la mayoría, como lo indica su distancia en el espacio vectorial de embedding.

Para más detalles sobre cómo trabajar con la API de Gemini y los embeddings, consulta la documentación de la API.

En este ejemplo usarás el modelo gemini-embedding-001 de la API de Gemini para generar tus embeddings.

EMBEDDINGS_MODEL="gemini-embedding-001"
prompt = """
    The quick brown fox jumps over the lazy dog.
"""

response = client.embeddings.create(
  model=EMBEDDINGS_MODEL,
  input=prompt,
)

print(len(response.data[0].embedding))
print(response.data[0].embedding[:4], '...')

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_58", line 6, in <module>
NameError: name 'client' is not defined

Una aplicación simple de los embeddings de texto es calcular la similitud entre oraciones (es decir, reseñas de productos, contenidos de documentos, etc.). Primero crearás un grupo de oraciones.

import pandas as pd


text = [
    "i really enjoyed the movie last night",
    "so many amazing cinematic scenes yesterday",
    "had a great time writing my Python scripts a few days ago",
    "huge sense of relief when my .py script finally ran without error",
    "O Romeo, Romeo, wherefore art thou Romeo?",
]

df = pd.DataFrame(text, columns=["text"])
df

Ahora puedes crear una función para generar embeddings, aplicar esa función a tu columna text del dataframe y guardarla en una nueva columna llamada embeddings.

def generate_embeddings(text):
  response = client.embeddings.create(
    model=EMBEDDINGS_MODEL,
    input=text,
  )
  return response.data[0].embedding

df["embeddings"] = df.apply(
    lambda x: generate_embeddings([x.text]), axis=1
)
df

File "/usr/local/google/home/giom/.gemini/jetski/scratch/cookbook-agentB-interactions/.venv/lib/python3.13/site-packages/pandas/core/apply.py", line 1183, in apply_series_generator
    results[i] = self.func(v, *self.args, **self.kwargs)
                 ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "Get_started_OpenAI_Compatibility.ipynb:cell_63", line 9, in <lambda>
  File "Get_started_OpenAI_Compatibility.ipynb:cell_63", line 2, in generate_embeddings
NameError: name 'client' is not defined

Ahora que tienes las representaciones de embeddings para todas las oraciones, puedes calcular sus similitudes.

from sklearn.metrics.pairwise import cosine_similarity

cos_sim_array = cosine_similarity(list(df.embeddings.values))

# display as DataFrame
analysis = pd.DataFrame(cos_sim_array, index=text, columns=text)
analysis

 in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_65", line 3, in <module>
  File "/usr/local/google/home/giom/.gemini/jetski/scratch/cookbook-agentB-interactions/.venv/lib/python3.13/site-packages/pandas/core/generic.py", line 6206, in __getattr__
    return object.__getattribute__(self, name)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^
AttributeError: 'DataFrame' object has no attribute 'embeddings'

También puedes graficarlo para una mejor visualización.

import seaborn as sns

ax = sns.heatmap(analysis, annot=True, cmap="Blues")
ax.xaxis.tick_top()
ax.set_xticklabels(text, rotation=90)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_67", line 3, in <module>
NameError: name 'analysis' is not defined

Generación de embeddings por lotes

Puedes usar el SDK de OpenAI para generar embeddings sin conexión y en grandes lotes a una tarifa reducida. La API sigue los mismos pasos que tomarías para generar contenido.

Comienza creando un archivo JSONL que contenga cada una de las solicitudes de embedding a procesar.

%%writefile embedding_requests.jsonl
{"custom_id": "request-1", "method": "POST", "url": "/v1/embeddings", "body": {"model": "gemini-embedding-001", "input": "I really enjoyed the movie last night"}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/embeddings", "body": {"model": "gemini-embedding-001", "input": "So many amazing cinematic scenes yesterday"}}

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
                  ~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "Get_started_OpenAI_Compatibility.ipynb:cell_69", line 1
    %%writefile embedding_requests.jsonl
    ^
SyntaxError: invalid syntax

Sube el archivo JSONL que contiene las solicitudes de embedding. Hasta que haya soporte para la API de carga de archivos de OpenAI, debes usar el SDK de Google GenAI para subir el archivo y hacer que los datos estén disponibles para la API de Gemini.

from google import genai
from google.genai import types

genai_client = genai.Client(api_key=GEMINI_API_KEY)

uploaded_file = genai_client.files.upload(
    file="embedding_requests.jsonl",
    config=types.UploadFileConfig(display_name="My embedding requests", mime_type="jsonl"),
)
print(f'{uploaded_file.name=}')

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_71", line 4, in <module>
NameError: name 'GOOGLE_API_KEY' is not defined

Ahora, con el archivo subido, crea un nuevo trabajo por lotes para procesar las solicitudes en el archivo JSONL.

batch = client.batches.create(
    input_file_id=uploaded_file.name,
    endpoint="/v1/embeddings",
    completion_window="24h"
)
print(f'{batch.id=}')

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_73", line 1, in <module>
NameError: name 'client' is not defined

if batch.status == 'completed':
    # Download the output file.
    file_content_bytes = genai_client.files.download(file=batch.output_file_id)
    file_content = file_content_bytes.decode('utf-8')

    # Print each output record.
    for i, line in enumerate(file_content.splitlines(), start=1):
            print(i, line[:100] + '...')

else:
    print(f'An error occurred. Batch status is "{batch.status}".')

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "Get_started_OpenAI_Compatibility.ipynb:cell_77", line 1, in <module>
NameError: name 'batch' is not defined

Próximos pasos

Haz más con Gemini

Si quieres usar más de las capacidades de Gemini y especialmente sus capacidades únicas no disponibles a través de la compatibilidad con OpenAI, deberías consultar el SDK de Google GenAI.

El Cookbook está lleno de ejemplos sobre cómo usarlo, pero se recomienda comenzar con el notebook Primeros pasos para familiarizarte con todos los modelos y capacidades del SDK.

Ejemplos relacionados

Consulta el resto del Cookbook. Aprenderás cómo usar la API en vivo , manejar múltiples herramientas o usar las habilidades de comprensión espacial de Gemini.

También consulta la guía de pensamiento que muestra explícitamente sus pensamientos y puede manejar razonamientos más complejos.

Lección del curso «Gemini API Cookbook (quickstarts)» de Google, publicado con licencia Apache 2.0. Traducción y adaptación al español de IA con Clase. IA con Clase no está afiliado a Google. Ver el original · Licencia

Esta lección es gratuita. El resto del curso se abre con la Membresía de IA con Clase, que incluye todos los cursos del catálogo. Ver precios

← Anterior Siguiente: Introducción a la conversión de texto a voz (TTS) →