Python on KnightLi Blog

Guía de instalación de uv: cómo elegir entre macOS, Linux, Windows, pipx, Homebrew y WinGet

Thu, 07 May 2026 23:23:58 +0800

uv es un gestor de toolchain de Python creado por Astral. Sirve para gestionar versiones de Python, entornos virtuales, dependencias, scripts, proyectos y herramientas. Tiene muchas formas de instalación. La documentación oficial ofrece instaladores independientes y también admite PyPI, Homebrew, WinGet, Scoop, Docker, GitHub Releases y Cargo.

Si solo quieres instalarlo rápido, da prioridad al instalador independiente oficial. Si prefieres mantener la versión mediante el gestor de paquetes del sistema, usa Homebrew, WinGet o Scoop. Si ya acostumbras instalar herramientas de Python en entornos aislados, puedes usar pipx.

Elección rápida

Escenario	Método recomendado	Comando
Instalación rápida en macOS / Linux	Instalador independiente oficial	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
macOS / Linux sin curl	Script oficial + wget	`wget -qO- https://astral.sh/uv/install.sh \| sh`
Instalación rápida en Windows	Instalador de PowerShell	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`
Instalación aislada de herramientas Python	pipx	`pipx install uv`
Instalación temporal o tradicional de Python	pip	`pip install uv`
Gestión de paquetes en macOS	Homebrew	`brew install uv`
Usuarios de MacPorts en macOS	MacPorts	`sudo port install uv`
Gestión de paquetes en Windows	WinGet	`winget install --id=astral-sh.uv -e`
Usuarios de Scoop en Windows	Scoop	`scoop install main/uv`
Usuarios de Rust	Cargo	`cargo install --locked uv`

Las opciones generales más recomendables son:

macOS / Linux: instalador independiente oficial;
Windows: instalador oficial de PowerShell o WinGet;
si ya gestionas herramientas CLI de Python con pipx: pipx install uv.

macOS y Linux: instalador oficial

El método oficial más directo consiste en descargar el script con curl y ejecutarlo con sh:

`1`	`curl -LsSf https://astral.sh/uv/install.sh \| sh`

Si el sistema no tiene curl, puedes usar wget:

`1`	`wget -qO- https://astral.sh/uv/install.sh \| sh`

Si quieres instalar una versión concreta, coloca el número de versión en la URL. Por ejemplo, el ejemplo oficial usa 0.11.11:

`1`	`curl -LsSf https://astral.sh/uv/0.11.11/install.sh \| sh`

Este método encaja con la mayoría de entornos personales de desarrollo. Es simple, multiplataforma y funciona mejor con el mecanismo oficial de actualización de uv.

El instalador coloca binarios como uv y uvx bajo el directorio del usuario, y puede modificar el shell profile para que los comandos puedan usarse directamente desde la terminal. Si no quieres que el instalador modifique PATH, revisa las opciones oficiales del installer, por ejemplo configurando UV_NO_MODIFY_PATH=1.

Windows: instalador de PowerShell

El método oficial en Windows es ejecutar el script de instalación con PowerShell:

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`

Para instalar una versión concreta, también puedes poner el número de versión en la URL:

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.11/install.ps1 \| iex"`

Aquí ExecutionPolicy ByPass permite obtener y ejecutar el script de instalación desde internet. Como hábito de seguridad, puedes revisar el contenido del script antes de ejecutarlo:

`1`	`powershell -c "irm https://astral.sh/uv/install.ps1 \| more"`

Si estás acostumbrado a gestores de paquetes de Windows, también puedes priorizar WinGet o Scoop.

Instalar con pipx

La documentación oficial indica que uv se publica en PyPI. Si lo instalas desde PyPI, se recomienda ponerlo en un entorno aislado, por ejemplo con pipx:

`1`	`pipx install uv`

Este método es adecuado si ya usas pipx como gestor de herramientas CLI de Python. Evita mezclar uv con el entorno del proyecto actual.

Si no tienes pipx, también puedes usar pip directamente:

`1`	`pip install uv`

Pero ten en cuenta que uv ofrece wheels precompilados en muchas plataformas. Si una plataforma no tiene un wheel compatible, se construirá desde código fuente, y en ese caso necesitarás una toolchain de Rust.

Mi recomendación: en una máquina personal, pipx install uv es más limpio que pip install uv; dentro de un entorno de proyecto, no recomiendo instalar uv como dependencia del proyecto.

Homebrew, MacPorts, WinGet y Scoop

Si prefieres gestores de paquetes del sistema, uv también admite canales comunes.

En macOS, usa Homebrew:

`1`	`brew install uv`

Los usuarios de MacPorts pueden usar:

`1`	`sudo port install uv`

En Windows, usa WinGet:

`1`	`winget install --id=astral-sh.uv -e`

Los usuarios de Scoop pueden usar:

`1`	`scoop install main/uv`

La ventaja de estos métodos es que delegan el mantenimiento en el gestor de paquetes del sistema. La desventaja es que el ritmo de actualización depende del origen de paquetes correspondiente, no del instalador oficial de uv.

Docker, GitHub Releases y Cargo

uv también ofrece imágenes Docker en GitHub Container Registry:

`1`	`ghcr.io/astral-sh/uv`

Esto sirve para CI, Dockerfiles, creación de imágenes y entornos temporales de ejecución. En uso real, conviene revisar también la documentación oficial de integración con Docker.

Si quieres descargar binarios manualmente, puedes hacerlo desde GitHub Releases. Cada página de release suele incluir binarios para las plataformas compatibles y explicar cómo llamar al instalador independiente usando una URL de GitHub.

Los usuarios de Rust también pueden instalar desde crates.io:

`1`	`cargo install --locked uv`

Pero este método compila desde código fuente y requiere una toolchain de Rust compatible. A menos que necesites instalarlo explícitamente desde el ecosistema Rust, los usuarios normales no tienen por qué elegir Cargo primero.

Actualizar uv

Si uv se instaló mediante el instalador independiente oficial, puedes usar el comando de autoactualización:

`1`	`uv self update`

La documentación oficial indica que actualizar uv vuelve a ejecutar el instalador y puede modificar el shell profile. Si no quieres que la actualización modifique PATH, configura:

`1`	`UV_NO_MODIFY_PATH=1`

Si lo instalaste de otra forma, debes actualizarlo con el gestor correspondiente. Por ejemplo, si lo instalaste con pip, usa:

`1`	`pip install --upgrade uv`

Homebrew, WinGet, Scoop y MacPorts también deben usar sus propios comandos de actualización.

Activar autocompletado de shell

uv admite autocompletado de shell. La documentación oficial recomienda comprobar primero cuál es tu shell actual:

`1`	`echo $SHELL`

Bash:

`1`	`echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc`

Zsh:

`1`	`echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc`

fish:

`1`	`echo 'uv generate-shell-completion fish \| source' > ~/.config/fish/completions/uv.fish`

PowerShell:

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

Si también usas uvx con frecuencia, puedes activar el autocompletado de uvx por separado.

Bash:

`1`	`echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc`

Zsh:

`1`	`echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc`

fish:

`1`	`echo 'uvx --generate-shell-completion fish \| source' > ~/.config/fish/completions/uvx.fish`

PowerShell:

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

Después de configurarlo, reinicia el shell o recarga el archivo de configuración correspondiente.

Desinstalar uv

Para desinstalar uv, primero puedes limpiar la caché y los datos gestionados por uv:

1
2
3

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

Después elimina los binarios.

macOS / Linux:

`1`	`rm ~/.local/bin/uv ~/.local/bin/uvx`

Windows:

1
2
3

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

La documentación oficial también recuerda que antes de 0.5.0, uv se instalaba en ~/.cargo/bin. Si actualizaste desde una versión antigua, es posible que los binarios viejos sigan allí y debas eliminarlos manualmente.

Qué hacer después de instalar

Después de instalar, conviene confirmar primero la versión:

`1`	`uv --version`

Luego puedes empezar con algunas tareas comunes:

uv python install
uv venv
uv pip install requests
uvx ruff --version

Si es un proyecto nuevo, puedes seguir aprendiendo:

uv init: inicializar un proyecto;
uv add: añadir dependencias;
uv sync: sincronizar el entorno;
uv run: ejecutar comandos dentro del entorno del proyecto;
uvx: ejecutar temporalmente herramientas CLI de Python.

Mi recomendación

En una máquina personal de desarrollo, prioriza el instalador independiente oficial, porque es el método más alineado con la documentación oficial de uv y admite uv self update.

Si usas Windows y no quieres ejecutar un script remoto, puedes usar WinGet o Scoop. Si usas macOS y prefieres que todas tus herramientas las gestione Homebrew, puedes usar directamente brew install uv.

Quienes ya gestionan herramientas CLI de Python con pipx pueden usar pipx install uv. Pero no recomiendo ejecutar pip install uv dentro del entorno virtual de un proyecto concreto, porque eso mezcla la toolchain con las dependencias del proyecto.

Si se trata de CI o construcción de contenedores, revisa primero Docker y GitHub Releases, y fija la versión según el flujo de creación de la imagen.

Enlaces relacionados

Documentación de instalación de uv: https://docs.astral.sh/uv/getting-started/installation/
uv First steps: https://docs.astral.sh/uv/getting-started/first-steps/
Integración de uv con Docker: https://docs.astral.sh/uv/guides/integration/docker/
uv GitHub Releases: https://github.com/astral-sh/uv/releases

Google LangExtract: extraiga datos estructurados de texto largo con LLM

Fri, 01 May 2026 02:58:21 +0800

LangExtract es una biblioteca Python de código abierto de Google para extraer información estructurada de texto no estructurado.

Su caso de uso es sencillo: proporcione un fragmento de texto, un mensaje y algunos ejemplos, luego deje que un modelo de lenguaje grande extraiga campos de acuerdo con su definición y organice el resultado en datos que puedan procesarse.

A diferencia de simplemente pedirle a un modelo que resuma algo, “LangExtract” se centra en tres cosas:

Extraer información en una estructura fija.
Preservar la relación entre los resultados extraídos y sus ubicaciones de origen.
Soporte de documentos largos e inspección visual.

Si a menudo necesita extraer entidades, eventos, relaciones o atributos de informes, documentos, notas médicas, contratos, registros o páginas web, este tipo de herramienta es más flexible que las expresiones regulares escritas a mano y más fácil de conectar a flujos de trabajo de datos posteriores que las simples preguntas estilo chat.

¿Qué problema resuelve?

Muchas tareas de extracción de texto parecen simples, pero resultan problemáticas en la práctica.

Por ejemplo, es posible que desee extraer:

Personas, organizaciones y ubicaciones.
Eventos, horarios y participantes.
Medicamentos, dosis y reacciones adversas.
Modelos, parámetros y precios de productos.
Cláusulas, obligaciones y plazos del contrato.
Tipos de errores y contexto de los registros.

Si el formato es fijo, pueden funcionar las expresiones regulares o los analizadores tradicionales.
Pero una vez que el texto se vuelve más natural, las reglas rápidamente se complican.

Los modelos de lenguaje grandes son buenos para comprender el lenguaje natural, pero pedirle directamente a un modelo que lo “extraiga” a menudo causa varios problemas:

El formato de salida es inestable.
No está claro de dónde proviene la información en el texto fuente.
Es fácil pasar por alto los documentos largos
El procesamiento por lotes es difícil
Los resultados son incómodos de revisar manualmente

LangExtract aborda esta capa del problema: integra la comprensión de LLM en un flujo de trabajo de extracción más controlable.

Características clave de LangExtract

1. Utilice ejemplos para restringir el formato de extracción

LangExtract no se basa en un mensaje vago de una sola línea. En cambio, utiliza indicaciones y ejemplos para decirle al modelo:

Qué extraer
Cómo se llama cada campo
Cómo se debe llenar cada campo
Qué hacer cuando la información es incierta

Este enfoque de pocas tomas funciona bien para la extracción de información.
Cuanto más se acerquen sus ejemplos a los datos reales, más estable se volverá la salida estructurada del modelo.

2. Los resultados extraídos pueden vincularse a la fuente

El peor tipo de resultado de extracción es el que parece correcto pero no se puede rastrear.

Uno de los puntos importantes de “LangExtract” es alinear los resultados extraídos con las ubicaciones de origen. Cuando revise más tarde, no solo verá un resultado JSON; también puedes volver al texto original y ver de dónde vino la información.

Esto es importante en escenarios que requieren revisión, como textos médicos, textos legales, material de investigación y documentos comerciales internos.

3. Soporte para documentos largos

La extracción de documentos largos a menudo se topa con límites de ventana de contexto, resultados perdidos y resultados duplicados.

LangExtract proporciona un flujo de trabajo para texto largo: divide el documento, procesa fragmentos en paralelo y luego organiza los resultados extraídos. Esto lo hace más adecuado para informes completos, artículos, páginas web largas y documentos masivos, en lugar de solo fragmentos cortos.

4. Inspección visual

Si los resultados de la extracción solo están disponibles como JSON, es fácil pasar por alto los problemas.

LangExtract admite la visualización de resultados extraídos, lo que facilita ver qué extrajo el modelo y de dónde proviene.
Esto es útil para ajustar indicaciones, comprobar extracciones omitidas y encontrar falsos positivos.

¿Cuándo debería usarlo?

LangExtract es adecuado cuando:

Es necesario extraer campos estructurados del texto en lenguaje natural.
El formato del texto no está completamente arreglado.
Debes preservar la relación entre los resultados extraídos y el texto fuente.
Necesita procesar documentos más largos.
Los resultados requieren revisión humana
El resultado se incluirá posteriormente en tablas, bases de datos o flujos de trabajo de análisis de datos.

Los ejemplos típicos incluyen:

Extracción de síntomas, medicamentos, dosis y reacciones del texto médico.
Extracción de partes, obligaciones, montos y plazos de los contratos.
Extraer temas, métodos y conclusiones de los artículos.
Extracción de parámetros de especificación de documentos de producto.
Extracción de tipos de problemas y resoluciones de registros de soporte.

Si sólo necesita un resumen temporal de un breve fragmento de texto, un modelo de chat normal es suficiente.
Si desea convertir texto en datos que puedan procesarse más adelante, LangExtract es la mejor opción.

Instalación básica

El proyecto admite la instalación a través de pip:

`1`	`pip install langextract`

También puedes instalarlo desde la fuente:

1
2
3

git clone https://github.com/google/langextract.git
cd langextract
pip install -e .

Si desea utilizar una API modelo, configure la clave API para el proveedor del modelo correspondiente.
La documentación del proyecto se centra en el uso de Gemini y también puede conectarse a otros proveedores de modelos a través de adaptadores.

Flujo de uso básico

Un flujo de trabajo típico se ve así:

Prepara el texto fuente.
Describa claramente el objetivo de extracción.
Proporcione algunos ejemplos
Llame a LangExtract para realizar la extracción.
Inspeccionar el resultado estructurado.
Genere una página de visualización para revisarla si es necesario.

El segundo y tercer paso son los más importantes.

El mensaje debe describir claramente la tarea, por ejemplo:

Extraer sólo información explícitamente presente en el texto.
No completes hechos faltantes de sentido común.
Deje los campos vacíos cuando falte información
Mantener la misma estructura de campos para el mismo tipo de entidad.
Conservar fragmentos de código fuente o posiciones en la salida

Los ejemplos deben ser lo más parecidos posible a las entradas reales.
Si el texto real tiene ruido, abreviaturas, saltos de línea o residuos de tabla, los ejemplos deberían reflejarlo.

Cosas a tener en cuenta

En primer lugar, no amplíe demasiado la tarea de extracción.

“Extraer información útil” es demasiado vago.
Una mejor instrucción sería “extraer el nombre del medicamento, la dosis, la frecuencia y las reacciones adversas”.

En segundo lugar, no confíe plenamente en los resultados del modelo.

LangExtract puede alinear los resultados con el texto fuente, pero eso no significa que el modelo nunca omitirá o extraerá incorrectamente información. Los escenarios importantes aún requieren controles de muestreo o revisión humana.

En tercer lugar, los ejemplos son más útiles que las explicaciones largas.

En las tareas de extracción de información, los modelos suelen basarse más en ejemplos para comprender el formato de salida.
En lugar de escribir un conjunto de reglas largas y abstractas, proporcione algunos ejemplos de alta calidad. Cuarto, preste atención al costo y la velocidad para documentos largos.

La división de documentos largos, la extracción paralela y las llamadas de modelos tienen costos. Antes del procesamiento por lotes, utilice un pequeño conjunto de muestra para ajustar la estructura de campos y mensajes.

¿En qué se diferencia de Regex o PNL tradicional?

Las expresiones regulares son buenas para formatos de texto estables y bien definidos.

Los canales de PNL tradicionales funcionan bien cuando los límites de las tareas son claros y el modelo o diccionario ya está preparado.

LangExtract es mejor para texto cuyo formato es menos fijo pero cuyo significado es claro.
No requiere que escribas una regla para cada expresión posible; en cambio, el LLM aprende el objetivo de extracción a partir de ejemplos.

Pero no es un reemplazo completo de las expresiones regulares:

Para texto de formato fijo, las expresiones regulares son más económicas y estables.
Para escenarios de alto riesgo, aún se requiere validación y revisión.
Para el procesamiento por lotes a gran escala, el costo de la llamada al modelo es importante

Un enfoque práctico es manejar las partes con reglas claras con código y usar LangExtract para las partes con más variación semántica.

¿Para quién es?

Es posible que desee consultar LangExtract si está realizando alguna de las siguientes acciones:

Convertir texto largo en tablas.
Extracción de entidades y relaciones de documentos.
Limpiar datos antes de ponerlos en una base de conocimientos.
Extracción de campos del texto comercial.
Construcción de un prototipo de extracción de información impulsado por LLM.
Preservar evidencia entre los resultados extraídos y el texto fuente.

No es una herramienta de tipo “haga clic una vez y comprenda cada documento”. Es más como una biblioteca para diseñar un flujo de trabajo de extracción de LLM.

Aún necesita diseñar campos, escribir ejemplos e inspeccionar los resultados.
Pero en comparación con escribir manualmente llamadas de modelo, unir mensajes y analizar resultados cada vez, proporciona un marco de extracción más completo.

Referencia

google/langextract

Pensamiento final

El valor de LangExtract hace que “permitir que un LLM encuentre información en texto” sea más controlable.

No es para resúmenes casuales. Es para tareas de extracción de información con requisitos de campos, evidencia y revisión.
Si su trabajo convierte a menudo textos largos en datos estructurados, vale la pena intentarlo.

Notas del proyecto rembg: una herramienta de eliminación de fondo local

Sun, 19 Apr 2026 08:56:01 +0800

rembg es una herramienta de eliminación de fondo de imágenes. Se puede utilizar como herramienta de línea de comandos, biblioteca de Python, servidor HTTP o contenedor Docker. Su propósito es sencillo: tomar una imagen como entrada y generar el primer plano con un canal alfa. Funciona bien para imágenes de productos, retratos, procesamiento de materiales y flujos de trabajo de imágenes automatizados.

La mejor parte es que puede ejecutarse localmente. Si no desea cargar imágenes de origen a un servicio de recorte en línea, necesita procesamiento por lotes o desea conectar la eliminación de fondo a scripts y sistemas comerciales, rembg es más fácil de automatizar que una herramienta web.

01 Instalación

La versión actual requiere Python >=3.11,<3.14. Elija el backend según su hardware:

`1`	`pip install "rembg[cpu]"`

Si necesita la CLI, agregue cli:

`1`	`pip install "rembg[cpu,cli]"`

Para entornos NVIDIA CUDA, instale la versión GPU:

`1`	`pip install "rembg[gpu,cli]"`

Para entornos AMD ROCm, primero instale onnxruntime-rocm siguiendo las instrucciones oficiales de ROCm, luego instale:

`1`	`pip install "rembg[rocm,cli]"`

La mayoría de los problemas con la versión de GPU no están en rembg en sí, sino en si coinciden onnxruntime-gpu, CUDA, cuDNN y las versiones del controlador. Si la instalación falla, primero confirme el flujo de trabajo con la versión de la CPU y luego ocúpese del entorno de la GPU.

02 Subcomandos CLI

Después de instalar la CLI, puede usar rembg directamente en la terminal. Proporciona principalmente 4 subcomandos:

i: procesa un solo archivo.
p: procesa una carpeta completa.
s: inicia un servidor HTTP.
b: procesa un flujo binario RGB de 24 píxeles, utilizado a menudo con FFmpeg.

Mostrar ayuda:

1
2

rembg --help
rembg i --help

Procese una única imagen local:

`1`	`rembg i input.png output.png`

Tubería en una imagen remota:

`1`	`curl -s http://input.png \| rembg i > output.png`

Especifique un modelo:

`1`	`rembg i -m u2netp input.png output.png`

Devuelve sólo la máscara:

`1`	`rembg i -om input.png mask.png`

Habilitar estera alfa:

`1`	`rembg i -a input.png output.png`

-a a veces puede producir cabello más natural, bordes borrosos y límites semitransparentes, pero es más lento y no mejora notablemente todas las imágenes.

03 Carpetas de procesamiento por lotes

El procesamiento por lotes es una de las partes más útiles de “rembg”. Coloque las imágenes de origen en un directorio y envíe los resultados a otro:

`1`	`rembg p path/to/input path/to/output`

Esté atento a los cambios de directorio y procese automáticamente imágenes nuevas o modificadas:

`1`	`rembg p -w path/to/input path/to/output`

Este modo funciona bien con scripts de descarga, limpieza de imágenes de productos y carpetas de materiales. Por ejemplo, suelte imágenes en “entrada” y deje que “rembg” genere archivos PNG transparentes en “salida”.

04 Utilizándolo como biblioteca de Python

Si desea integrarlo en su propio script, la forma más sencilla es “eliminar”:

from rembg import remove

with open("input.png", "rb") as i:
    with open("output.png", "wb") as o:
        input_data = i.read()
        output_data = remove(input_data)
        o.write(output_data)

También puedes procesar imágenes PIL directamente:

from rembg import remove
from PIL import Image

input_image = Image.open("input.png")
output_image = remove(input_image)
output_image.save("output.png")

Para el procesamiento por lotes, reutilice una sesión para que el modelo no se inicialice nuevamente para cada imagen:

from pathlib import Path
from rembg import remove, new_session

session = new_session()

for file in Path("input").glob("*.png"):
    output = file.parent / f"{file.stem}.out.png"
    with open(file, "rb") as i:
        with open(output, "wb") as o:
            o.write(remove(i.read(), session=session))

Si está creando un servicio de procesamiento de imágenes de larga duración, la reutilización de sesiones suele ser una mejor opción que llamar repetidamente a la CLI.

05 Iniciando un servidor HTTP

rembg también puede iniciar un servidor HTTP directamente:

`1`	`rembg s --host 0.0.0.0 --port 7000 --log_level info`

Después del inicio, visite:

`1`	`http://localhost:7000/api`

Eliminar el fondo de una URL:

`1`	`curl -s "http://localhost:7000/api/remove?url=http://input.png" -o output.png`

Sube una imagen local:

`1`	`curl -s -F file=@input.jpg "http://localhost:7000/api/remove" -o output.png`

Si solo necesita la API y no necesita la interfaz de usuario de Gradio, desactive la interfaz de usuario para reducir el uso inactivo de la CPU:

`1`	`rembg s --no-ui`

El modo servidor es adecuado para herramientas internas, flujos de automatización u otras aplicaciones. Pero no es un sistema completo de gestión de activos de imágenes. La autenticación, la limitación de velocidad, las colas y la limpieza de archivos aún deben gestionarse fuera de él.

06 Uso de Docker

La versión de CPU puede usar la imagen oficial directamente:

`1`	`docker run -v .:/data danielgatis/rembg i /data/input.png /data/output.png`

La aceleración CUDA requiere NVIDIA Container Toolkit en el host y, por lo general, requiere crear una imagen a partir del Dockerfile_nvidia_cuda_cudnn_gpu del proyecto:

`1`	`docker build -t rembg-nvidia-cuda-cudnn-gpu -f Dockerfile_nvidia_cuda_cudnn_gpu .`

Ejecutar ejemplo:

docker run --rm -it --gpus all \
  -v /dev/dri:/dev/dri \
  -v $PWD:/data \
  rembg-nvidia-cuda-cudnn-gpu \
  i -m birefnet-general /data/input.png /data/output.png

El archivo README oficial señala que la imagen de la GPU es mucho más grande que la imagen de la CPU y los archivos del modelo no están incluidos en la imagen. Para evitar descargar modelos repetidamente, monte el directorio del modelo:

`1`	`docker run -v /path/to/models:/root/.u2net ...`

07 Opciones de modelo

Cuando rembg usa un modelo por primera vez, lo descarga automáticamente a ~/.u2net/. Los modelos comunes incluyen:

u2net: un modelo de propósito general para casos comunes.
u2netp: una versión ligera con velocidad y tamaño más amigables.
u2net_human_seg: enfocado a la segmentación humana.
u2net_cloth_seg: enfocado al análisis de ropa.
silueta: similar a u2net, pero más pequeña.
isnet-general-use: un modelo más nuevo de propósito general.
isnet-anime: enfocado a la segmentación de personajes de anime.
birefnet-general: un modelo de imagen general utilizado en el ejemplo README.
sam: puede trabajar con parámetros adicionales como puntos de aviso.

En la práctica, no elijas sólo por el nombre del modelo. Las imágenes de productos, los retratos, las imágenes de anime, los fondos complejos y los objetos transparentes tienen requisitos diferentes. Un enfoque más seguro es elegir un conjunto de imágenes representativo, ejecutar varios modelos, comparar bordes, áreas omitidas, eliminaciones falsas y velocidad, y luego decidir el modelo predeterminado.

Si desea utilizar un modelo .onnx personalizado, colóquelo en el directorio del modelo predeterminado ~/.u2net/ y configúrelo cuando sea necesario:

`1`	`MODEL_CHECKSUM_DISABLED=1`

Esto puede evitar que rembg sobrescriba su archivo de modelo debido a la lógica de suma de comprobación.

08 Casos de uso adecuados

rembg se adapta bien a estas tareas:

Generar por lotes imágenes de productos con fondo transparente.
Extraiga primeros planos de retratos, fotografías de identificación e imágenes de materiales.
Integre la eliminación de fondo en scripts de Python o servicios backend.
Implementar una API de eliminación de fondo simple en una red interna.
Utilice tuberías FFmpeg para procesar fotogramas de vídeo o secuencias de imágenes.
Mantenga los materiales sensibles a la privacidad o protegidos por derechos de autor lejos de los servicios en línea de terceros.

Es menos adecuado para estos casos:

Necesita bordes retocados a mano y materiales transparentes complejos.
Cada imagen debe alcanzar una calidad de fotografía comercial estable.
Quieres una herramienta de diseño en línea completa en lugar de solo eliminar el fondo.
No desea mantener un entorno Python o Docker.
Su entorno de controlador de GPU, CUDA o ROCm ya está desordenado y el proyecto debe iniciarse rápidamente.

09 Consejos de uso

Si solo procesa imágenes ocasionalmente, la versión de la CPU es suficiente:

`1`	`pip install "rembg[cpu,cli]"`

Para procesar por lotes miles de imágenes, considere:

Reutilizar una sesión de Python.
Arreglando el directorio del modelo para evitar descargas repetidas.
Uso de un SSD para entradas, salidas y archivos de modelo.
Probar primero la calidad del modelo en un lote pequeño.
Decidir si la aceleración de la GPU vale la pena después.

El valor de la GPU es principalmente el rendimiento por lotes. Para el procesamiento ocasional de una sola imagen, el costo de configuración puede ser mayor que el tiempo ahorrado. Especialmente en Windows, cuando las versiones CUDA, cuDNN y onnxruntime-gpu no coinciden, la versión de CPU puede ser la opción más práctica.

10 toma rápida

rembg es simple, de código abierto y flexible: puede ejecutarse como una CLI, llamarse desde Python, exponer puntos finales HTTP o empaquetarse con Docker. Es un buen componente base para la eliminación automática del fondo local.

Pero no es un borrador mágico. Los fondos complejos, los bordes finos del sujeto, los materiales transparentes, la preservación de las sombras y los retoques de calidad comercial aún pueden requerir trabajo manual o un flujo de trabajo más especializado. Al implementar la automatización por lotes, es mejor realizar una revisión humana o un paso de recuperación de muestras fallidas.

Si el objetivo es eliminar fondos de un lote de imágenes rápidamente manteniendo el proceso local, vale la pena mantener “rembg” en la caja de herramientas.

Enlaces relacionados

Proyecto GitHub: https://github.com/danielgatis/rembg
LÉAME: https://github.com/danielgatis/rembg/blob/main/README.md
Lanzamientos: https://github.com/danielgatis/rembg/releases
Matriz de instalación de ONNX Runtime: https://onnxruntime.ai/

Guía práctica de codex-quota: uso local, web y de Docker con comandos CLI originales

Thu, 16 Apr 2026 18:13:04 +0800

Qué hace este proyecto

codex-quota es una herramienta liviana para verificar el uso de la cuota de ChatGPT Codex, con datos obtenidos de https://chatgpt.com/backend-api/wham/usage.

Características principales:

Admite consultas de una sola cuenta y de varias cuentas (account/*.auth.json).
Genera five_hour%, weekly%, weekly_reset y marca la fuente (network o cache).
Utiliza reintentos de retroceso exponencial para fallas temporales (408, 429, 5xx).
Incluye almacenamiento en caché local para reducir las solicitudes repetidas cuando la cuota ya está agotada.
Proporciona un panel web, API JSON y páginas de administración de archivos de autenticación.

Ventajas:

Ligero: se ejecuta con scripts simples y dependencias mínimas.
Práctico: admite puntos de entrada CLI y Web.
Implementable: funciona con Docker y Docker Compose.
Fácil de operar: incluye reintento, caché y soporte de actualización programada.

Prepare las credenciales de la cuenta primero

Cree archivos de credenciales en account/<name>.auth.json, por ejemplo:

{
  "tokens": {
    "access_token": "eyJ...",
    "account_id": "user-xxxxxxxx"
  }
}

Explicación:

La API de uso requiere access_token y account_id.
<nombre> en el nombre del archivo se utiliza como nombre de cuenta en la salida.

Uso de CLI local (conservar los comandos originales)

Instalar dependencias:

`1`	`pip install -r requirements.txt`

Explicación: instala las dependencias del proyecto.

Consultar todas las cuentas:

`1`	`python codex_quota.py`

Explicación: lee account/*.auth.json y genera un resumen de cuota para todas las cuentas.

Consulta una cuenta:

`1`	`python codex_quota.py your_account_name`

Explicación: solo consulta cuenta/nombre_de_cuenta.auth.json.

Forzar actualización (omitir caché):

`1`	`python codex_quota.py --refresh`

Explicación: ignora el caché local y recupera datos nuevos directamente.

Opciones CLI (alineadas con README)

account_name: nombre de cuenta opcional (sin .auth.json).
--account-dir: directorio de autenticación, cuenta predeterminada.
--chatgpt-url: punto final de API de cuota.
--raw-json: imprime el cuerpo completo de la respuesta JSON.
--raw-headers: imprime encabezados de respuesta.
--refresh: ignora el caché.
--retries: recuento de reintentos, valor predeterminado 3.
--retry-delay: retraso de reintento base en segundos, valor predeterminado 2.0.

Uso del panel web (conservar el comando original)

Iniciar el servicio:

`1`	`python codex_quota_service.py --host 0.0.0.0 --port 8081`

Explicación: inicia el servicio HTTP escuchando en el puerto 8081.

URL de acceso: http://localhost:8081

Opciones de servicio:

--host: dirección de enlace, predeterminado 0.0.0.0.
--port: puerto de servicio, predeterminado 8081.
--interval-segundos: intervalo de actualización programado, predeterminado 3600.
--account-dir: directorio de autenticación, cuenta predeterminada.
--state-file: ruta del archivo de estado, predeterminado <account-dir>/codex_quota_web_results.json.
--account-name: modo de cuenta única opcional.
--chatgpt-url: punto final de API de cuota.
--retries: recuento de reintentos.
--retry-delay: retraso de reintento base.
--refresh: ignora el caché CLI durante las ejecuciones programadas.

Puntos finales HTTP (para automatización)

GET /: página del panel de control.
GET /api/results: últimos resultados en JSON.
GET /refresh: activa la actualización inmediata y redirige a /.
GET /auth: enumera los archivos de autenticación.
GET /auth/new: formulario para crear un archivo de autenticación.
GET /auth/edit?name=<cuenta>: formulario para editar el archivo de autenticación.
POST /auth/save: crea/actualiza el archivo de autenticación.
POST /auth/delete: elimina el archivo de autenticación.

Uso de Docker (conservar los comandos originales)

Construir imagen:

`1`	`docker build -t codex-quota .`

Explicación: construye el proyecto actual como imagen codex-quota.

Ejecutar contenedor (mapa 8081):

`1`	`docker run --rm -p 8081:8081 -v ./account:/app/account codex-quota`

Explicación:

--rm: elimina el contenedor automáticamente después de salir.
-p 8081:8081: asigna el puerto del host al puerto del contenedor.
-v ./account:/app/account: monta las credenciales locales en el contenedor.

URL de acceso: http://localhost:8081

Uso de Docker Compose (conservar el comando original)

Inicio:

`1`	`docker compose up --build`

Explicación: cree e inicie servicios basados en docker-compose.yml.

URL de acceso: http://localhost:8081

Consejos de uso

Para escenarios de múltiples cuentas, use primero el Panel de control para una vista unificada y administración de autenticación.
Para alertas o automatización, prefiera GET /api/results.
No envíe valores reales de access_token a repositorios públicos.
Si ve muchas fallas temporales, aumente --retries y --retry-delay.

Compartir un Agent Skill para recortar y normalizar imágenes de producto de e-commerce

Thu, 09 Apr 2026 21:43:50 +0800

product-cutout-normalize es un Agent Skill para imágenes de producto.

Procesa imágenes originales y las convierte en imágenes cuadradas con fondo transparente y especificaciones uniformes. Sus reglas predeterminadas son:

Lienzo 1024x1024
Fondo transparente
Conservar el sujeto lo más completo posible
Convertir automáticamente sujetos verticales a orientación horizontal
Centrar el sujeto
Normalizar el ancho visible del sujeto a 820px

Es adecuado para materiales de e-commerce, bibliotecas de producto y preprocesamiento de imágenes para páginas de detalle.

Qué problema resuelve este skill

Después de un recorte básico, muchas imágenes de producto todavía tienen estos problemas:

Restos de borde blanco o fondo gris claro
Orientación horizontal/vertical del sujeto inconsistente
Tamaño de lienzo inconsistente
Tamaño del sujeto muy variable
Pequeños puntos de ruido en áreas transparentes

Este skill procesa con un flujo fijo:

Recorte con Gemini
Limpieza de fondo claro en los bordes
Eliminación de pequeños fragmentos de ruido
Rotación de imágenes verticales a horizontales
Escalado según ancho objetivo
Colocación en el centro de un lienzo transparente uniforme

Las imágenes exportadas quedan más ordenadas y son más adecuadas para uso por lotes.

Escenarios adecuados

Encaja con estas necesidades:

Procesar fotos de producto por lotes
Exportar PNG con fondo transparente de forma uniforme
Unificar el tamaño visual principal
Necesitar un flujo estable y repetible

Si solo procesas pocas imágenes, o si cada imagen necesita ajustar manualmente la composición, quizá no sea la herramienta más adecuada.

Inicio rápido

La forma más directa de ejecución:

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite`

Antes de ejecutar necesitas:

GEMINI_API_KEY
google-genai
Pillow

Instalar dependencias:

`1`	`.\.venv\Scripts\python.exe -m pip install google-genai pillow`

Configurar variable de entorno:

`1`	`$env:GEMINI_API_KEY="your_api_key"`

Reglas de salida

Salida predeterminada:

PNG con fondo transparente
Lienzo 1024x1024
Ancho del sujeto 820px
Sujeto centrado
Se limpian pequeños puntos de ruido

Así que no es solo un script de quitar fondo, sino más bien un script de organización de imágenes de producto.

Parámetros principales

Parámetros habituales:

--model Predeterminado: gemini-2.5-flash-image
--canvas-size Tamaño del lienzo cuadrado de salida, predeterminado 1024
--target-width Ancho visible del sujeto, predeterminado 820
--min-component-pixels Fragmentos transparentes con menos píxeles que este valor se eliminan, predeterminado 500
--overwrite Sobrescribe directamente si el archivo de salida ya existe

Por ejemplo:

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" ".\input" ".\output" --canvas-size 1280 --target-width 960 --overwrite`

Flujo de procesamiento

El flujo es simple:

Recorte con Gemini
Limpieza de fondo claro en los bordes
Eliminación de pequeños fragmentos de ruido
Rotación de imágenes verticales a horizontales
Escalado según ancho objetivo
Colocación en el centro de un lienzo transparente uniforme

Diferencia frente a scripts comunes de recorte

Comparado con un script común de eliminación de fondo, también trata:

Orientación uniforme del sujeto
Tamaño uniforme del sujeto
Tamaño uniforme del lienzo
Limpieza de pequeños fragmentos de ruido
Resultados más adecuados para colocarse directamente en una biblioteca de materiales

Código fuente de SKILL.md

Abajo se conserva el código fuente completo de SKILL.md, sin cambios:

---
name: product-cutout-normalize
description: Run a reusable Gemini product-image pipeline that removes backgrounds, preserves the full subject, rotates tall products to a horizontal orientation, centers them on a 1024x1024 transparent canvas, and normalizes the visible subject width to 820px. Use when the user wants a repeatable cutout-and-normalize workflow for product photos or asks to batch-process product images into standardized square PNG assets.
---

# Product Cutout Normalize

Use this skill when product photos need the same deterministic finishing pipeline:

- Gemini cutout from the original photo
- border cleanup to transparent
- preserve the full subject
- rotate to horizontal when the subject is taller than it is wide
- center on a `1024x1024` transparent canvas
- normalize the visible subject width to `820px`

## Quick Start

Run the bundled script:

```powershell
& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite
```

Required environment:

- `GEMINI_API_KEY`
- `google-genai`
- `Pillow`

## Workflow

1. Confirm the request matches this standard pipeline. If the user asks for a different canvas size, subject width, or layout rule, pass explicit flags instead of changing the script.
2. Run the bundled script on the input directory.
3. If a result looks misaligned, inspect the alpha bounding box and small detached artifacts first; this pipeline already removes tiny alpha components by default.
4. Report the exact input and output directories used, plus any non-default flags.

## Script

Primary entry point:

- `scripts/run_pipeline.py`

Key flags:

- `--model`: Gemini image model, default `gemini-2.5-flash-image`
- `--canvas-size`: output square size, default `1024`
- `--target-width`: visible subject width after normalization, default `820`
- `--min-component-pixels`: remove detached alpha specks smaller than this, default `500`
- `--overwrite`: replace existing outputs in the destination directory

## Repo Integration

If the current project already has [`scripts/nano_banana_cutout.py`](/c:/Work/my_shop/scripts/nano_banana_cutout.py), prefer that repo script when the user wants the same pipeline inside this repository. Use the bundled skill script when the task is cross-project reuse or when you want the workflow to stay self-contained inside the skill.

Código fuente de scripts/run_pipeline.py

Abajo se conserva el código fuente completo de scripts/run_pipeline.py, sin cambios:

from __future__ import annotations

import argparse
import os
from collections import deque
from pathlib import Path

from PIL import Image

try:
    from google import genai
except ImportError as exc:  # pragma: no cover
    raise SystemExit(
        "Missing dependency: google-genai. Install it with "
        r"'.\.venv\Scripts\python.exe -m pip install google-genai'."
    ) from exc


PROMPT = (
    "Remove the entire background from this product photo and return only the product "
    "on a fully transparent background as a PNG. Keep the full product intact, preserve "
    "thin cable details, clean the inner loops and holes, and do not add any new objects "
    "or shadows."
)
DEFAULT_CANVAS_SIZE = 1024
DEFAULT_TARGET_WIDTH = 820
DEFAULT_MIN_COMPONENT_PIXELS = 500
SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp"}


def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35


def to_pil_image(image_obj) -> Image.Image:
    if isinstance(image_obj, Image.Image):
        return image_obj
    pil_image = getattr(image_obj, "_pil_image", None)
    if isinstance(pil_image, Image.Image):
        return pil_image
    as_pil = getattr(image_obj, "pil_image", None)
    if isinstance(as_pil, Image.Image):
        return as_pil
    raise TypeError(f"Unsupported image object type: {type(image_obj)!r}")


def make_transparent_from_borders(image: Image.Image) -> Image.Image:
    rgba = image.convert("RGBA")
    width, height = rgba.size
    pixels = rgba.load()

    visited: set[tuple[int, int]] = set()
    queue: deque[tuple[int, int]] = deque()

    def push_if_bg(x: int, y: int) -> None:
        if (x, y) in visited:
            return
        r, g, b, _ = pixels[x, y]
        if is_light_background_pixel(r, g, b):
            visited.add((x, y))
            queue.append((x, y))

    for x in range(width):
        push_if_bg(x, 0)
        push_if_bg(x, height - 1)
    for y in range(height):
        push_if_bg(0, y)
        push_if_bg(width - 1, y)

    while queue:
        x, y = queue.popleft()
        for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
            if 0 <= nx < width and 0 <= ny < height:
                push_if_bg(nx, ny)

    for x, y in visited:
        pixels[x, y] = (0, 0, 0, 0)

    return rgba


def remove_small_components(image: Image.Image, min_component_pixels: int) -> Image.Image:
    if min_component_pixels <= 0:
        return image

    rgba = image.convert("RGBA")
    alpha = rgba.getchannel("A")
    width, height = rgba.size
    alpha_pixels = alpha.load()
    rgba_pixels = rgba.load()
    visited: set[tuple[int, int]] = set()

    for y in range(height):
        for x in range(width):
            if alpha_pixels[x, y] == 0 or (x, y) in visited:
                continue

            queue: deque[tuple[int, int]] = deque([(x, y)])
            visited.add((x, y))
            component: list[tuple[int, int]] = []

            while queue:
                cx, cy = queue.popleft()
                component.append((cx, cy))
                for nx, ny in ((cx - 1, cy), (cx + 1, cy), (cx, cy - 1), (cx, cy + 1)):
                    if 0 <= nx < width and 0 <= ny < height:
                        if alpha_pixels[nx, ny] == 0 or (nx, ny) in visited:
                            continue
                        visited.add((nx, ny))
                        queue.append((nx, ny))

            if len(component) < min_component_pixels:
                for px, py in component:
                    r, g, b, _ = rgba_pixels[px, py]
                    rgba_pixels[px, py] = (r, g, b, 0)

    return rgba


def normalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
) -> Image.Image:
    rgba = image.convert("RGBA")
    bbox = rgba.getchannel("A").getbbox()
    if bbox is None:
        return Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))

    subject = rgba.crop(bbox)
    if subject.height > subject.width:
        subject = subject.rotate(-90, expand=True, resample=Image.Resampling.BICUBIC)
        rotated_bbox = subject.getchannel("A").getbbox()
        if rotated_bbox is not None:
            subject = subject.crop(rotated_bbox)

    scale = target_width / subject.width
    subject = subject.resize(
        (target_width, max(1, int(round(subject.height * scale)))),
        Image.Resampling.LANCZOS,
    )

    canvas = Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))
    offset_x = (canvas_size - subject.width) // 2
    offset_y = (canvas_size - subject.height) // 2
    canvas.alpha_composite(subject, (offset_x, offset_y))
    return canvas


def finalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> Image.Image:
    transparent = make_transparent_from_borders(image)
    cleaned = remove_small_components(transparent, min_component_pixels)
    return normalize_product_image(cleaned, canvas_size=canvas_size, target_width=target_width)


def save_first_image_part(
    response,
    dst: Path,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    parts = getattr(response, "parts", None)
    if parts is None and getattr(response, "candidates", None):
        parts = response.candidates[0].content.parts

    if not parts:
        raise RuntimeError("Model returned no content parts.")

    for part in parts:
        inline_data = getattr(part, "inline_data", None)
        if inline_data is None and isinstance(part, dict):
            inline_data = part.get("inline_data")

        if inline_data is None:
            continue

        if hasattr(part, "as_image"):
            image = to_pil_image(part.as_image())
            dst.parent.mkdir(parents=True, exist_ok=True)
            finalize_product_image(
                image,
                canvas_size=canvas_size,
                target_width=target_width,
                min_component_pixels=min_component_pixels,
            ).save(dst)
            return

        data = getattr(inline_data, "data", None)
        if data:
            dst.parent.mkdir(parents=True, exist_ok=True)
            with open(dst, "wb") as handle:
                handle.write(data)
            with Image.open(dst) as image:
                processed = finalize_product_image(
                    image,
                    canvas_size=canvas_size,
                    target_width=target_width,
                    min_component_pixels=min_component_pixels,
                )
                processed.save(dst.with_suffix(".png"))
            if dst.suffix.lower() != ".png":
                dst.unlink(missing_ok=True)
            return

    raise RuntimeError("Model returned text only and no edited image.")


def process_image(
    src: Path,
    dst: Path,
    client,
    model: str,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    with Image.open(src).convert("RGBA") as image:
        response = client.models.generate_content(
            model=model,
            contents=[PROMPT, image],
        )

    save_first_image_part(
        response,
        dst,
        canvas_size=canvas_size,
        target_width=target_width,
        min_component_pixels=min_component_pixels,
    )


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Cut out product images with Gemini and normalize them to square transparent PNGs."
    )
    parser.add_argument("input_dir", type=Path)
    parser.add_argument("output_dir", type=Path)
    parser.add_argument("--model", default="gemini-2.5-flash-image")
    parser.add_argument("--canvas-size", type=int, default=DEFAULT_CANVAS_SIZE)
    parser.add_argument("--target-width", type=int, default=DEFAULT_TARGET_WIDTH)
    parser.add_argument("--min-component-pixels", type=int, default=DEFAULT_MIN_COMPONENT_PIXELS)
    parser.add_argument("--overwrite", action="store_true")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise SystemExit("Missing GEMINI_API_KEY environment variable.")
    if not args.input_dir.is_dir():
        raise SystemExit(f"Input directory does not exist: {args.input_dir}")
    if args.canvas_size <= 0:
        raise SystemExit("--canvas-size must be positive.")
    if args.target_width <= 0 or args.target_width > args.canvas_size:
        raise SystemExit("--target-width must be positive and no larger than --canvas-size.")
    if args.min_component_pixels < 0:
        raise SystemExit("--min-component-pixels must be >= 0.")

    args.output_dir.mkdir(parents=True, exist_ok=True)
    client = genai.Client(api_key=api_key)

    for src in sorted(args.input_dir.iterdir()):
        if not src.is_file() or src.suffix.lower() not in SUPPORTED_EXTENSIONS:
            continue
        dst = args.output_dir / f"{src.stem}.png"
        if dst.exists() and not args.overwrite:
            print(f"skip {dst}")
            continue
        process_image(
            src,
            dst,
            client,
            args.model,
            canvas_size=args.canvas_size,
            target_width=args.target_width,
            min_component_pixels=args.min_component_pixels,
        )
        print(dst)


if __name__ == "__main__":
    main()

Descargar adjunto: product-cutout-normalize.7z

Cómo llamar a Google Nano Banana para recortar fondos de imágenes

Thu, 09 Apr 2026 20:10:48 +0800

Este artículo usa un script Python realmente ejecutable para demostrar cómo llamar a la capacidad de edición de imágenes Nano Banana de Google y recortar fondos de imágenes de producto.

El objetivo de esta implementación es muy claro:

Leer imágenes de producto desde un directorio
Llamar al modelo de imagen de Google para eliminar el fondo
Hacer una limpieza local adicional del fondo transparente sobre la imagen devuelta
Exportar finalmente como PNG con fondo transparente

Si ya tienes un lote de imágenes de producto con fondo blanco, fotos de auriculares o cables, y quieres generar rápidamente imágenes de fondo transparente aptas para e-commerce, esta forma es bastante directa.

Qué hace este código

Este script se divide principalmente en 4 partes:

Definir el prompt para que el modelo sepa que debe “quitar fondo, conservar sujeto, no añadir sombras”
Llamar a la interfaz de generación de imágenes de google-genai
Extraer el resultado de imagen desde la respuesta del modelo
Usar lógica local para convertir fondos claros de los bordes en transparencia, reduciendo restos de borde

Es decir, no se limita a enviar una imagen al modelo y terminar, sino que encadena “edición con modelo + posprocesamiento local”.

Preparación antes de ejecutar

Primero instala dependencias:

`1`	`.\.venv\Scripts\python.exe -m pip install google-genai pillow`

Cómo obtener GEMINI_API_KEY

GEMINI_API_KEY es la clave usada para llamar a Gemini API. Según el quickstart oficial de Google, si todavía no tienes una key, puedes crearla directamente en Google AI Studio.

Pasos:

Abre Google AI Studio.
Inicia sesión con tu cuenta de Google.
Busca la página Get API key o API keys.
Crea una nueva API key.
Copia la key generada.
Configúrala como variable de entorno local para que el script pueda leerla.

Si la página todavía no tiene un proyecto disponible, normalmente hay que completar primero la inicialización del proyecto y después volver a la página de API Key para crear la clave.

Después de obtener la key, configura la variable de entorno:

`1`	`$env:GEMINI_API_KEY="your_api_key"`

Si usas cmd, puedes escribir:

`1`	`set GEMINI_API_KEY=your_api_key`

Si configuras a la vez GEMINI_API_KEY y GOOGLE_API_KEY, en ejecución normalmente se leerá primero GOOGLE_API_KEY, así que se recomienda conservar solo una para evitar confusión.

Ejemplo de estructura de directorios

El script recibe dos parámetros:

input_dir: directorio de imágenes de entrada
output_dir: directorio de imágenes de salida

Por ejemplo:

images/
  product1.jpg
  product2.png

output/

Cómo ejecutarlo

Suponiendo que el script se llame cutout.py, se ejecuta así:

`1`	`.\.venv\Scripts\python.exe .\cutout.py .\images .\output`

Si quieres cambiar de modelo, también puedes pasar el parámetro explícitamente:

`1`	`.\.venv\Scripts\python.exe .\cutout.py .\images .\output --model gemini-2.5-flash-image`

El script recorrerá estos formatos dentro del directorio de entrada:

.jpg
.jpeg
.png
.webp

Al terminar, generará archivos PNG con fondo transparente y el mismo nombre en el directorio de salida.

Flujo principal de llamada

La llamada clave a Google Nano Banana está aquí:

response = client.models.generate_content(
    model=model,
    contents=[PROMPT, image],
)

Aquí se pasan dos contenidos:

Un prompt de texto PROMPT
Una imagen PIL.Image

El prompt le pide al modelo eliminar el fondo completo de la imagen de producto, conservar solo el sujeto y enfatiza varios puntos:

Conservar el producto completo
Conservar detalles de cables y líneas finas
Limpiar huecos internos y zonas anulares
No añadir objetos nuevos
No añadir sombras

Este tipo de prompt influye mucho en la calidad del recorte, especialmente en detalles como cables de auriculares, bordes transparentes y zonas huecas.

Por qué hacer otro posprocesamiento local

Después de que el modelo devuelve el resultado, el script no lo guarda directamente, sino que ejecuta make_transparent_from_borders(image).

La idea de este paso es:

Buscar píxeles de fondo claros desde los bordes de la imagen
Usar búsqueda en anchura para marcar todas las zonas claras conectadas
Convertir finalmente esas zonas en transparentes

La ventaja es que puede limpiar mejor algunos bordes blancos residuales, fondos gris claro y zonas de borde poco limpias.

La condición para decidir “si es fondo” está aquí:

def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35

En términos simples:

El color debe ser suficientemente claro
La diferencia entre los tres canales RGB no debe ser grande

Esto encaja bien con fondos blancos, gris claro o casi de color sólido en imágenes de producto.

Código fuente completo

Abajo se conserva el código fuente completo actual, para que puedas reutilizarlo o modificarlo directamente:

from __future__ import annotations

import argparse
import os
from pathlib import Path
from collections import deque

from PIL import Image

try:
    from google import genai
except ImportError as exc:  # pragma: no cover
    raise SystemExit(
        "Missing dependency: google-genai. Install it with "
        r"'.\.venv\Scripts\python.exe -m pip install google-genai'."
    ) from exc


PROMPT = (
    "Remove the entire background from this product photo and return only the product "
    "on a fully transparent background as a PNG. Keep the full product intact, preserve "
    "thin cable details, clean the inner loops and holes, and do not add any new objects "
    "or shadows."
)


def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35


def to_pil_image(image_obj) -> Image.Image:
    if isinstance(image_obj, Image.Image):
        return image_obj
    pil_image = getattr(image_obj, "_pil_image", None)
    if isinstance(pil_image, Image.Image):
        return pil_image
    as_pil = getattr(image_obj, "pil_image", None)
    if isinstance(as_pil, Image.Image):
        return as_pil
    raise TypeError(f"Unsupported image object type: {type(image_obj)!r}")


def make_transparent_from_borders(image: Image.Image) -> Image.Image:
    rgba = image.convert("RGBA")
    width, height = rgba.size
    pixels = rgba.load()

    visited: set[tuple[int, int]] = set()
    queue: deque[tuple[int, int]] = deque()

    def push_if_bg(x: int, y: int) -> None:
        if (x, y) in visited:
            return
        r, g, b, _ = pixels[x, y]
        if is_light_background_pixel(r, g, b):
            visited.add((x, y))
            queue.append((x, y))

    for x in range(width):
        push_if_bg(x, 0)
        push_if_bg(x, height - 1)
    for y in range(height):
        push_if_bg(0, y)
        push_if_bg(width - 1, y)

    while queue:
        x, y = queue.popleft()
        for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
            if 0 <= nx < width and 0 <= ny < height:
                push_if_bg(nx, ny)

    for x, y in visited:
        pixels[x, y] = (0, 0, 0, 0)

    return rgba


def save_first_image_part(response, dst: Path) -> None:
    parts = getattr(response, "parts", None)
    if parts is None and getattr(response, "candidates", None):
        parts = response.candidates[0].content.parts

    if not parts:
        raise RuntimeError("Model returned no content parts.")

    for part in parts:
        inline_data = getattr(part, "inline_data", None)
        if inline_data is None and isinstance(part, dict):
            inline_data = part.get("inline_data")

        if inline_data is None:
            continue

        if hasattr(part, "as_image"):
            image = to_pil_image(part.as_image())
            dst.parent.mkdir(parents=True, exist_ok=True)
            make_transparent_from_borders(image).save(dst)
            return

        data = getattr(inline_data, "data", None)
        mime_type = getattr(inline_data, "mime_type", "")
        if data:
            dst.parent.mkdir(parents=True, exist_ok=True)
            with open(dst, "wb") as handle:
                handle.write(data)
            with Image.open(dst) as img:
                processed = make_transparent_from_borders(img)
                processed.save(dst.with_suffix(".png"))
            if dst.suffix.lower() != ".png":
                dst.unlink(missing_ok=True)
            return

    raise RuntimeError("Model returned text only and no edited image.")


def process_image(src: Path, dst: Path, client, model: str) -> None:
    with Image.open(src).convert("RGBA") as image:
        response = client.models.generate_content(
            model=model,
            contents=[PROMPT, image],
        )
    save_first_image_part(response, dst)


def main() -> None:
    parser = argparse.ArgumentParser(description="Use Nano Banana / Gemini image editing to cut out product images.")
    parser.add_argument("input_dir", type=Path)
    parser.add_argument("output_dir", type=Path)
    parser.add_argument("--model", default="gemini-2.5-flash-image")
    args = parser.parse_args()

    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise SystemExit("Missing GEMINI_API_KEY environment variable.")

    client = genai.Client(api_key=api_key)
    exts = {".jpg", ".jpeg", ".png", ".webp"}

    for src in sorted(args.input_dir.iterdir()):
        if not src.is_file() or src.suffix.lower() not in exts:
            continue
        dst = args.output_dir / f"{src.stem}.png"
        process_image(src, dst, client, args.model)
        print(dst)


if __name__ == "__main__":
    main()

Qué conviene optimizar después

Si quieres seguir usando este script para producción por lotes, después puedes añadir:

Reintentos ante fallos, para evitar que una sola imagen rompa todo el lote
Registro de logs, para localizar qué imagen falló
Umbrales configurables para distintos fondos
Escaneo recursivo de subdirectorios
Vista previa comparativa entre imagen original y resultado

Resumen

Si solo quieres entender rápido “cómo llamar a Google Nano Banana para recortar fondos”, el núcleo son tres pasos:

Instalar google-genai y Pillow
Configurar GEMINI_API_KEY
Usar client.models.generate_content() pasando prompt e imagen

El valor de este código está en que no solo llama al modelo, sino que añade posprocesamiento de fondo transparente, por lo que sirve mejor para tareas reales de recorte de imágenes de producto.