Python on KnightLi Blog

¿Cómo utilizar Agent-Reach? Proporcionar al agente AI capacidades de búsqueda y lectura multiplataforma

Sat, 06 Jun 2026 22:26:00 +0800

Panniantong/Agent-Reach es una herramienta que amplía la capacidad de AI Agent para “ver Internet”. La descripción del proyecto es muy sencilla: permita que el Agente lea y busque información de plataformas como Twitter, Reddit, YouTube, GitHub, Bilibili, Xiaohongshu, etc. a través de una CLI, y enfatice las cero tarifas de API.

El valor de dichas herramientas radica en complementar las capacidades de adquisición de información externa del Agente. El modelo en sí quedará obsoleto y la búsqueda en el navegador no estará necesariamente estructurada. Agent-Reach quiere convertir la lectura multiplataforma en una herramienta utilizable.

Adecuado para qué hacer

Es adecuado para:

Investigaciones recientes sobre puntos críticos;
Observación de la opinión pública en las redes sociales;
Resumen del contenido del vídeo y extracción de transcripciones;
Colección de señales del proyecto GitHub;
Búsqueda de contenido Bilibili/Xiaohongshu;
Conectar fuentes de información a clientes Claude Code, Cursor y MCP;
Realizar selección de contenidos, estudios de mercado y observación de productos competitivos.

Si a menudo le pide a AI que escriba artículos de tendencia, organice materiales de video y busque comentarios de la comunidad, este tipo de herramienta será mucho mejor que el chat puro.

¿A qué debes prestar atención al usarlo?

Los rastreadores multiplataforma naturalmente tienen límites:

Las reglas de la plataforma y las estrategias anti-rastreo pueden cambiar;
El estado de inicio de sesión, las cookies y la información privada deben manejarse con precaución;
Los resultados del rastreo no son iguales a los hechos, son solo muestras;
El contenido de las diferentes plataformas varía mucho;
Confirmar el cumplimiento y los términos de la plataforma antes del uso comercial.

Las “tarifas de API cero” son tentadoras, pero no significan costos cero. El mantenimiento, el control de riesgos, la estabilidad y el cumplimiento son factores que influyen.

La diferencia entre motores de búsqueda.

Los motores de búsqueda son buenos para encontrar páginas web y Agent-Reach prefiere “convertir el contenido de la plataforma en herramientas de Agent”. Si su objetivo es que el Agente complete investigaciones, resúmenes, comparaciones y redacción de manuscritos continuamente, será más conveniente.

Pero si sólo desea consultar un documento oficial, una búsqueda normal puede resultar más sencilla.

Resumen

El posicionamiento de Agent-Reach es muy práctico: brindarle a Agent un par de ojos que pueden ver contenido en múltiples plataformas. Es adecuado para investigación, análisis de contenido y seguimiento de tendencias, pero no trate los resultados del rastreo como conclusiones autorizadas.

En lo que respecta a la implementación, es mejor utilizarla junto con la verificación de datos, la anotación de fuentes y la revisión manual.

Fuentes de referencia

Panniantong/Agent-Reach - GitHub

¿Cómo utilizar MemPalace? ¿Para qué escenarios de agentes es adecuado el sistema de memoria AI de código abierto?

Sat, 06 Jun 2026 22:26:00 +0800

MemPalace/mempalace es un sistema de memoria de IA de código abierto. La descripción del proyecto dice que es un “sistema de memoria de IA de código abierto” y enfatiza los puntos de referencia. Simplemente comprenda que quiere proporcionar una capa de memoria sostenible para LLM y Agent, en lugar de depender únicamente de la ventana de contexto actual.

La memoria a largo plazo es un problema que el sistema del agente no puede evitar. Sin memoria, el Agente parecerá nuevo cada vez; si la memoria es mala, generará preferencias erróneas, hechos obsoletos y datos privados en tareas posteriores.

¿Para qué es adecuado?

MemPalace es más adecuado para estos escenarios:

El asistente personal de IA recuerda las preferencias y los objetivos a largo plazo;
El Agente de Programación recuerda los acuerdos de proyectos y los obstáculos históricos;
El agente de servicio o de operaciones recuerda el contexto del usuario;
Múltiples rondas de tareas de investigación conservan conclusiones escalonadas;
Conectar capacidades de memoria a diferentes clientes a través de MCP;
Construir servicios de memoria para implementación local o privada.

El objetivo de este tipo de sistema no es “guardar más registros”, sino qué guardar, cómo recuperarlo, cuándo olvidarlo y cómo corregir errores.

Diferencias con el RAG ordinario

El RAG ordinario se parece más a “buscar información”; El sistema de memoria se parece más a “acumular experiencia”.

Los objetos de RAG suelen ser documentos, páginas web y bases de conocimiento. El sistema de memoria manejará el diálogo, las preferencias del usuario, las trayectorias de las tareas, los resultados de las decisiones y las experiencias de fracaso. Los dos se pueden combinar, pero no los mezcles.

Si sólo desea solicitar contenido PDF, RAG es suficiente; Si desea que el Agente crezca entre sesiones, necesita un sistema de memoria.

¿A qué debes prestar atención al usarlo?

Hay varios problemas difíciles con la memoria a largo plazo:

Los recuerdos deben ser visibles, editables y eliminables;
No conservar conjeturas temporales como hechos;
Necesidad de diferenciar entre preferencias del usuario, hechos, estado de la tarea y experiencia;
Los datos sensibles deben tener permisos y políticas de retención;
Los viejos recuerdos pueden estar desactualizados y es necesario descomponerlos o revisarlos.

Los sistemas de memoria de IA tienen más miedo de “recordar cosas incorrectas con seguridad”. Así que no te centres sólo en la tasa de recuperación, sino también en el mecanismo de corrección de errores.

Resumen

MemPalace merece atención porque los agentes de IA están pasando de ser herramientas únicas a socios de colaboración a largo plazo. Siempre que los agentes trabajan entre sesiones, los sistemas de memoria se convierten en infraestructura.

Pero más recuerdos no son mejores. Un sistema de memoria verdaderamente útil debería permitir al usuario controlar lo que recuerda y permitir al Agente obtener el contexto correcto cuando sea necesario.

Fuentes de referencia

MemPalace/mempalace - GitHub

¿Cómo utilizar OpenAI Whisper? Posicionamiento y límites de los modelos de reconocimiento de voz de código abierto.

Sat, 06 Jun 2026 22:26:00 +0800

openai/whisper es un proyecto de reconocimiento de voz de código abierto OpenAI. La dirección de la tesis es Reconocimiento robusto del habla mediante supervisión débil a gran escala. Permite a muchas personas obtener, por primera vez con un umbral bajo, capacidades de transliteración de voz multilingüe que se pueden ejecutar localmente.

Aunque hoy en día existen más rápido: Whisper, Whisper.cpp, varios ASR en la nube y modelos de voz de nueva generación, el Whisper original sigue siendo el punto de partida para comprender el ecosistema ASR de código abierto.

¿Para qué es adecuado?

Los usos comunes de Whisper incluyen:

Audio a texto;
Generación de subtítulos de vídeo;
Transcripción de podcasts;
Actas de reuniones;
Reconocimiento de voz multilingüe;
Traducción de voz al inglés;
Borrador de subtítulos y recuperación de contenidos.

Sus ventajas son robustez, multilenguaje, código abierto y madurez ecológica. Muchas herramientas posteriores están optimizadas en torno al modelo o interfaz de Whisper.

Usa límites

Whisper no es un dictador universal:

El ruido, los acentos y la superposición de varias personas afectarán los resultados;
Los términos y nombres profesionales requieren posprocesamiento;
El audio largo debe segmentarse;
Es posible que las marcas de tiempo no siempre sean perfectas;
La velocidad de inferencia y el uso de recursos de la versión original pueden no ser adecuados para la producción;
Preste atención al procesamiento y almacenamiento local de audio privado.

Si necesita servicios de producción de alto rendimiento, es posible que desee considerar implementaciones más rápidas de Whisper, Whisper.cpp, por lotes, de cuantificación y de GPU.

¿Para quién es adecuado?

Adecuado:

Herramientas de subtítulos y transliteración;
Procesar podcasts, cursos y grabaciones de conferencias;
Estudiar modelos ASR;
Crear un servicio local de voz a texto;
Organizar contenidos multilingües.

Si sólo transcribes ocasionalmente una pieza de audio, un servicio alojado puede ser menos problemático; Si le importa la privacidad y el costo, una implementación local es más atractiva.

Resumen

Whisper es un proyecto icónico en el ecosistema de reconocimiento de voz de código abierto. No es necesariamente la implementación más rápida en la actualidad, pero sigue siendo una piedra angular importante de la cadena de herramientas ASR.

Si realiza transcripciones de audio, subtítulos o procesamiento de datos de voz, vale la pena comenzar a comprender Whisper y luego elegir una versión optimizada según los requisitos de rendimiento.

Fuentes de referencia

openai/susurro - GitHub

¿Qué es VibeVoice? ¿Vale la pena seguir el proyecto de IA de voz open source de Microsoft?

Sat, 06 Jun 2026 22:26:00 +0800

microsoft/VibeVoice es un proyecto de IA de voz open source de Microsoft. La descripción del repositorio es “Open-Source Frontier Voice AI”. Por su posicionamiento, apunta a generación de voz, interacción por voz y Voice AI de frontera.

La IA de voz está pasando de “voz a texto / texto a voz” a una experiencia de interacción más completa: tono natural, audio largo, múltiples hablantes, emoción, conversación en tiempo real y capacidades multilingües serán cada vez más importantes.

Por qué vale la pena seguirlo

Hay varias razones para prestar atención a VibeVoice:

Es un proyecto open source de Microsoft, por lo que su ecosistema podría avanzar rápido;
Usa una pila en Python, adecuada para investigación y experimentación;
La IA de voz es una entrada importante para los Agent multimodales;
Los modelos de voz open source reducen la barrera para despliegues privados;
TTS, asistentes de voz y generación de contenido pueden beneficiarse.

Si trabajas en pódcast, avatares virtuales, asistentes de voz, atención al cliente, productos educativos o Agent multimodales, la capacidad de voz será cada vez más crítica.

Escenarios en los que podría encajar

Conviene observarlo para:

Texto a voz;
Lectura de textos largos;
Contenido de voz con varios personajes;
Prototipos de interacción por voz;
Generación de voz local o privada;
Doblaje para video con IA y humanos digitales;
Experiencias de voz multilingües.

Las capacidades concretas todavía dependen del modelo, los ejemplos, la licencia y los requisitos de hardware. No conviene sacar conclusiones solo por el título del proyecto.

Límites de uso

Los proyectos de generación de voz requieren especial cuidado:

Clonación de voz y autorización;
Riesgo de abuso, fraude y falsificación;
Licencia para uso comercial;
Origen de los conjuntos de datos;
Marca de agua y divulgación de voz generada;
Velocidad de inferencia y requisitos de VRAM.

Cuanto más realista sea la voz, más importante será el límite de seguridad.

Resumen

VibeVoice es un proyecto de IA de voz open source que vale la pena seguir. Que sea apto para producción dependerá de su documentación, calidad del modelo, coste de despliegue y detalles de licencia.

Si te interesan los asistentes de voz, TTS, doblaje de videos con IA o Agent multimodales, puedes guardarlo y observar sus ejemplos y la reacción de la comunidad.

Fuentes de referencia

microsoft/VibeVoice - GitHub

Cómo usar EverOS: un framework local para memoria a largo plazo en AI Agents

Sat, 06 Jun 2026 22:26:00 +0800

EverMind-AI/EverOS es un framework Python open source para añadir memoria a largo plazo a AI Agents y aplicaciones de chat. Su objetivo no es crear otro chatbot, sino organizar conversaciones, trayectorias de agentes y conocimiento de archivos en una capa de memoria estructurada, recuperable y evolutiva.

Lo más interesante es su diseño de almacenamiento: EverOS no encierra la memoria en una base de datos opaca, sino que trata Markdown como Source of Truth. Puedes abrirlo, editarlo, buscar con grep, versionarlo con Git e incluso verlo en Obsidian.

Qué problema resuelve

En muchos Agents, la “memoria” es solo contexto de corto plazo:

Recuerda hoy y olvida mañana;
Una herramienta sabe algo que otra no sabe;
Preferencias de usuario, experiencia de proyecto y casos fallidos quedan dispersos en chats;
RAG puede buscar archivos, pero no siempre conserva “experiencias vividas”;
Cuando el sistema de memoria depende de bases de datos complejas, el coste de mantenimiento sube para equipos pequeños.

EverOS quiere ser una base de memoria a largo plazo más ligera. Separa la memoria del usuario y la memoria del Agent: los usuarios tienen Profile, Episodes, Facts y Foresights; los Agents tienen Cases y Skills. Así no solo se “recuerda una frase”, sino que se acumulan personas, tareas, experiencias y procedimientos.

Estructura técnica

El README explica claramente los principios centrales de EverOS:

Markdown as Source of Truth: toda memoria termina en archivos .md;
Lightweight three-piece storage: Markdown + SQLite + LanceDB;
EverAlgo se encarga de los algoritmos de extracción de memoria, mientras EverOS orquesta y persiste.

El layout de almacenamiento se parece a esto:

~/.everos/
├── default_app/
│   └── default_project/
│       ├── users/<user_id>/
│       │   ├── user.md
│       │   ├── episodes/
│       │   ├── .atomic_facts/
│       │   └── .foresights/
│       └── agents/<agent_id>/
│           ├── agent.md
│           ├── .cases/
│           └── skills/
└── .index/
    ├── sqlite/system.db
    └── lancedb/*.lance/

Markdown es la fuente de verdad, SQLite gestiona estado y colas, y LanceDB gestiona vectores, BM25 y scalar filters. Esta combinación es mucho más ligera que un stack completo con MongoDB, Elasticsearch, Milvus, Redis y Kafka, y encaja mejor con desarrolladores individuales y equipos pequeños.

Inicio rápido

La instalación es sencilla:

1
2
3

uv pip install everos
# or
pip install everos

Inicializa la configuración:

`1`	`everos init`

Luego inicia el servicio:

`1`	`everos server start`

El endpoint stack de EverOS es compatible con OpenAI protocol, así que puede conectarse a OpenAI, OpenRouter, vLLM, Ollama, DeepInfra y servicios similares. Solo tienes que ajustar el BASE_URL correspondiente y las API Keys en .env.

Si necesitas procesar imágenes, PDF, audio, documentos Office u otros contenidos no textuales, instala la extensión multimodal:

`1`	`uv pip install 'everos[multimodal]'`

La conversión de documentos Office depende de LibreOffice. Sin LibreOffice, PDF, imágenes y audio no se ven afectados, pero archivos .doc, .docx, .ppt, .pptx, .xls y .xlsx fallarán al procesarse.

Escenarios adecuados

EverOS encaja mejor en:

Asistentes de programación con IA que recuerdan convenciones de proyecto, errores pasados y flujos habituales;
Colaboración multi-agent con memoria a largo plazo compartida;
Asistentes personales que recuerdan preferencias, experiencias y objetivos;
Asistentes internos de conocimiento que combinan archivos y experiencia conversacional;
Investigación, análisis de datos y operaciones que necesitan acumular casos entre sesiones;
Equipos que quieren mantener memoria en archivos locales en lugar de entregarla por completo a una plataforma en la nube.

No es tan adecuado para FAQs simples. Para eso basta con un RAG común. El valor de EverOS está en que la memoria se vuelve más rica con el uso, no solo en buscar documentos estáticos.

Límites de uso

La memoria a largo plazo suena atractiva, pero tiene trampas:

Recordar mal es más peligroso que olvidar, así que la extracción de memoria necesita verificación humana;
La privacidad del usuario y la información sensible deben poder verse, borrarse y exportarse;
Un Agent no debe confiar ciegamente en conclusiones antiguas solo porque estén en memoria;
La separación entre usuarios, proyectos y Agents debe diseñarse con cuidado;
Que Markdown sea editable es una ventaja, pero también implica manejar la sincronización del índice tras ediciones manuales.

Por eso EverOS encaja mejor como infraestructura que como producto final. En la capa de aplicación debes decidir qué puede recordarse, cuándo, durante cuánto tiempo, quién puede leerlo y cómo corregir errores.

Resumen

El diseño de EverOS resulta muy atractivo: usa Markdown como fuente de verdad, SQLite y LanceDB como índices, y devuelve la memoria a largo plazo desde bases de datos opacas hacia un sistema de archivos legible, editable y versionable.

Si estás creando AI Agents, asistentes personales, asistentes de programación o plataformas multi-agent, y ya te has encontrado con el problema de “al terminar la conversación todo se olvida”, EverOS merece estudio. No es un cerebro universal, pero ofrece un prototipo práctico de sistema operativo de memoria.

Referencias

EverMind-AI/EverOS - GitHub

ai-engineering-from-scratch: una ruta para construir ingeniería de IA desde cero

Sat, 06 Jun 2026 22:22:56 +0800

rohitg00/ai-engineering-from-scratch es una ruta amplia para aprender ingeniería de IA. Su lema es “Learn it. Build it. Ship it for others.” El énfasis no está solo en leer conceptos, sino en implementar sistemas de IA desde sus fundamentos.

Si ya sabes llamar a las APIs de OpenAI, Claude o Gemini, pero quieres completar conocimientos de base sobre machine learning, Transformers, entrenamiento, inferencia e ingeniería, este proyecto merece estar en tus marcadores.

No es una lista de recursos más

Muchos repositorios de aprendizaje de IA solo juntan papers, cursos y enlaces de blogs. ai-engineering-from-scratch se parece más a un índice de curso: cada tema indica si es Learn o Build, y muchas partes te piden implementar desde cero en Python.

Cubre un rango muy amplio:

Fundamentos de matemáticas y machine learning;
Redes neuronales y deep learning;
Visión por computadora;
Audio y voz;
Profundización en Transformers;
IA generativa;
Aprendizaje por refuerzo;
LLMs desde cero;
Optimización de inferencia;
AI Agent e ingeniería de producción.

Esta ruta no es para quien quiere lanzar una app de IA esta noche, pero sí para quien quiere fortalecer de verdad sus bases de ingeniería de IA.

Qué caracteriza la ruta

Una característica clara es el avance por fases. Por ejemplo, la parte de Transformers empieza con los problemas de RNN, luego pasa a self-attention, multi-head attention, positional encoding, Transformer completo, BERT, GPT, T5, ViT, MoE, KV cache, Flash Attention, Scaling Laws y construcción de un Transformer desde cero.

La parte de LLM tampoco trata solo de prompts. Cubre:

Tokenizers: BPE, WordPiece, SentencePiece;
Construir un tokenizer desde cero;
Pipelines de datos para preentrenamiento;
Preentrenar un Mini GPT;
Entrenamiento distribuido;
Instruction Tuning;
RLHF;
DPO;
Optimización de inferencia y despliegue.

Este tipo de contenido ayuda a pasar de “sé usar APIs de IA” a “entiendo por qué los modelos funcionan así”.

Por qué importa hacerlo desde cero

“Desde cero” suena lento, pero tiene una ventaja: entiendes qué ocultan los frameworks.

Si has escrito attention por tu cuenta, es más fácil entender:

Por qué los contextos más largos consumen más memoria;
Por qué KV cache acelera la inferencia;
Qué optimiza realmente Flash Attention;
En qué se diferencian RoPE y ALiBi en positional encoding;
Por qué MoE no es simplemente aumentar parámetros;
Por qué tokenization afecta el rendimiento multilingüe;
Qué problemas distintos resuelven fine-tuning, RLHF y DPO.

Estos detalles quizá no se usan al llamar una API. Pero cuando haces selección de modelos, optimización de costes, despliegue local, sistemas de contexto largo o frameworks de Agents, se vuelven muy útiles.

Para quién es

Esta ruta encaja mejor con:

Personas que ya escriben Python y quieren aprender ingeniería de IA de forma sistemática;
Desarrolladores de aplicaciones de IA que no se sienten seguros sobre los fundamentos de los modelos;
Desarrolladores que quieren pasar de llamar APIs a ser AI Engineers;
Personas que preparan investigación sobre LLMs, optimización de inferencia o entrenamiento de modelos;
Quienes prefieren aprender construyendo, no solo viendo videos o leyendo artículos.

No es ideal para principiantes absolutos. Conviene tener al menos Python, matemáticas básicas y algunos conceptos de machine learning, o será fácil atascarse.

Cómo empezar de forma estable

No intentes tragarte todo el repositorio de una vez. Lo más práctico es elegir una ruta según tu objetivo:

Quieres crear apps de IA: prioriza LLMs, Agents, inferencia e ingeniería;
Quieres entender modelos: empieza por redes neuronales, Transformers y LLM from scratch;
Quieres productos de voz: mira audio, Whisper, TTS y voice assistant pipeline;
Quieres generación de imágenes: mira generative AI, diffusion, Stable Diffusion y ControlNet;
Quieres fundamentos: empieza por matemáticas, machine learning y deep learning.

Lo mejor es dejar un pequeño proyecto en cada fase. Leer el índice se siente bien, pero el valor real aparece al ejecutar un tokenizer, attention, mini GPT, RAG o servicio de inferencia.

Relación con el desarrollo normal de apps de IA

Muchas aplicaciones de IA hoy no necesitan entrenar modelos desde cero. Puedes usar APIs en la nube, bases vectoriales, motores de workflow y algunas llamadas a herramientas para crear un prototipo rápido.

Pero si quieres ir más lejos, aparecen preguntas como:

¿Por qué este modelo de contexto largo es tan lento?
¿Por qué RAG recuperó la respuesta pero el modelo no la usó?
¿Por qué algunas capacidades empeoraron después del fine-tuning?
¿Por qué el despliegue local se queda sin VRAM?
¿Por qué las llamadas a herramientas del Agent son inestables?
¿Por qué modelos con parámetros similares tienen costes tan diferentes?

En ese momento, el conocimiento de bajo nivel deja de ser decoración y se convierte en capacidad de depuración.

Resumen

ai-engineering-from-scratch es para personas que quieren fortalecer seriamente las bases de la ingeniería de IA. No promete atajos ni es solo una colección de marcadores; divide muchos módulos centrales de IA en fases que se pueden aprender, implementar y entregar.

Si solo haces apps simples de IA, no necesitas leerlo entero. Pero si quieres entender no solo cómo llamar APIs, sino también modelos, entrenamiento, inferencia, optimización y despliegue de ingeniería, este repositorio puede servir como ruta a largo plazo.

Referencias

rohitg00/ai-engineering-from-scratch - GitHub

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

faster-whisper: un motor de transcripción Whisper más rápido

Fri, 01 May 2026 22:31:26 +0800

faster-whisper es una implementación de inferencia de Whisper mantenida por SYSTRAN. Usa CTranslate2 como backend, mantiene un flujo cercano a Whisper y hace que la velocidad de inferencia, el uso de memoria y la flexibilidad de despliegue sean más adecuados para trabajo de ingeniería.

Si has usado openai/whisper, puedes pensar en faster-whisper como una alternativa más orientada a producción. La interfaz sigue girando alrededor de cargar un modelo, transcribir audio y leer resultados segmentados, pero la capa de ejecución es más rápida y más fácil de ajustar para CPU, GPU, cuantización y batching.

Qué problema resuelve

Whisper funciona bien, pero la implementación original suele encontrar varios problemas cuando se despliega directamente:

El audio largo puede tardar bastante en transcribirse.
El uso de memoria GPU puede ser alto.
La ejecución en CPU funciona, pero la velocidad puede no ser ideal.
El throughput no siempre es fácil de escalar al procesar grandes lotes de audio o video.

faster-whisper optimiza principalmente estos puntos. Su README indica que, con la misma precisión, puede ser hasta 4 veces más rápido que openai/whisper usando menos memoria. Con cuantización de 8 bits, la velocidad puede mejorar aún más.

Instalación

En un entorno Python normal, instálalo directamente:

`1`	`pip install faster-whisper`

Si quieres usar GPU, asegúrate de que las versiones locales de CUDA, cuDNN y CTranslate2 sean compatibles. Este es el punto más fácil para tropezar: el código puede estar bien, pero la inferencia puede fallar al cargar el modelo o ejecutar la primera solicitud si el driver GPU y el runtime CUDA no coinciden.

Uso básico

El ejemplo mínimo es directo:

from faster_whisper import WhisperModel

model_size = "large-v3"

model = WhisperModel(model_size, device="cuda", compute_type="float16")

segments, info = model.transcribe("audio.mp3", beam_size=5)

print("Detected language '%s' with probability %f" % (info.language, info.language_probability))

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

Los parámetros clave son:

Parámetro	Propósito
`model_size`	Selecciona el tamaño del modelo Whisper, como `small`, `medium` o `large-v3`
`device`	Dispositivo de inferencia, normalmente `cuda` o `cpu`
`compute_type`	Precisión de cálculo, como `float16`, `int8_float16` o `int8`
`beam_size`	Anchura de búsqueda de decodificación; valores mayores suelen ser más estables pero más lentos

Si tu objetivo es una transcripción local rápida, empieza probando medium o large-v3. Si la memoria GPU es limitada, considera la cuantización.

Elegir CPU o GPU

Con una GPU NVIDIA, prefiere:

`1`	`model = WhisperModel("large-v3", device="cuda", compute_type="float16")`

Si la memoria GPU no alcanza, cambia a:

`1`	`model = WhisperModel("large-v3", device="cuda", compute_type="int8_float16")`

Sin GPU, ejecútalo en CPU:

`1`	`model = WhisperModel("small", device="cpu", compute_type="int8")`

El modo CPU encaja mejor con tareas ligeras, trabajos en segundo plano poco frecuentes o servidores sin tarjeta gráfica. Para mucho audio largo, la GPU sigue siendo la mejor opción.

Transcripción por lotes

faster-whisper también ofrece transcripción por lotes. El batching es útil para muchos audios cortos o cuando necesitas mayor throughput de GPU:

from faster_whisper import WhisperModel, BatchedInferencePipeline

model = WhisperModel("turbo", device="cuda", compute_type="float16")
batched_model = BatchedInferencePipeline(model=model)
segments, info = batched_model.transcribe("audio.mp3", batch_size=16)

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

Un batch_size mayor no siempre es mejor. Mejora el throughput, pero también aumenta la presión sobre la memoria GPU. En la práctica, prueba valores como 4, 8 y 16 paso a paso hasta encontrar un punto estable para tu máquina.

VAD y marcas de tiempo por palabra

La transcripción de voz suele tener que lidiar con silencios largos, ruido de fondo y alineación de subtítulos. faster-whisper incluye parámetros prácticos que se pueden activar directamente durante la transcripción.

Activar VAD:

`1`	`segments, info = model.transcribe("audio.mp3", vad_filter=True)`

Obtener marcas de tiempo por palabra:

segments, info = model.transcribe("audio.mp3", word_timestamps=True)

for segment in segments:
    for word in segment.words:
        print("[%.2fs -> %.2fs] %s" % (word.start, word.end, word.word))

VAD es útil para grabaciones de reuniones, podcasts y repeticiones de directos con secciones largas de silencio. Las marcas de tiempo por palabra son útiles para subtítulos, revisión de transcripciones y resaltado de palabras en reproductores.

Elegir un modelo

La elección del modelo depende sobre todo de precisión, velocidad y recursos de la máquina.

Escenario	Recomendación
Pruebas rápidas	`small` o `medium`
Contenido chino priorizando calidad	`large-v3`
Memoria GPU ajustada	`int8_float16` o un modelo más pequeño
Tareas en segundo plano con CPU	Modelo pequeño más `int8`
Muchos audios cortos	Probar `BatchedInferencePipeline`

Para voz en chino, empieza con large-v3 si la calidad importa. Si la máquina va demasiado justa, reduce el tamaño del modelo o usa cuantización. No mires solo la velocidad al principio: si baja la calidad de transcripción, el tiempo extra de revisión manual puede anular el tiempo de inferencia ahorrado.

Casos de uso adecuados

faster-whisper encaja bien para:

Generar subtítulos de video.
Transcribir podcasts, reuniones y grabaciones de cursos.
Crear flujos locales de transcripción para Bilibili, YouTube y videos similares.
Archivar y buscar contenido de audio por lotes.
Enviar contenido hablado a RAG, bases de conocimiento o sistemas de búsqueda.

No resuelve directamente tareas de nivel superior como diarización de hablantes, resumen o segmentación por capítulos, pero puede servir como una capa de transcripción estable. Puedes añadir pyannote para diarización y un LLM para resumen y limpieza estructurada.

Sugerencias de despliegue

Para uso real, depura en este orden:

Usa un clip de audio de 1 a 3 minutos para confirmar que el entorno corre correctamente.
Prueba la precisión con muestras que coincidan con tu idioma y calidad de audio objetivo.
Revisa el uso de memoria GPU antes de decidir si activar cuantización.
Divide primero el audio largo, para que una tarea fallida no obligue a repetirlo todo.
Guarda salidas TXT y SRT para facilitar la revisión posterior.

Para tareas del lado del servidor, carga el modelo durante el inicio del servicio en vez de recargarlo por cada solicitud. Cargar el modelo toma tiempo, y recargarlo con frecuencia también puede volver menos estable la gestión de memoria GPU.

Resumen

El valor de faster-whisper es que convierte Whisper en un componente de transcripción más adecuado para uso sostenido. No es un modelo distinto; es un backend de inferencia y una interfaz de ingeniería más eficientes.

Para flujos personales, puede convertir rápidamente videos, reuniones y audio de cursos en texto. Para tareas de servidor, puedes ajustar rendimiento con GPU, cuantización, batching y VAD. Siempre que el entorno de la máquina esté configurado correctamente, es más adecuado que la implementación original de Whisper para trabajos estables y por lotes de speech-to-text.

Proyecto: https://github.com/SYSTRAN/faster-whisper

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.

Comprobar uso y cuota de Codex

Sun, 12 Apr 2026 00:01:33 +0800

Si quieres comprobar la cuota restante de una cuenta de Codex, un pequeño script local puede llamar directamente al endpoint /backend-api/wham/usage de ChatGPT.

El flujo general es simple:

Leer tokens.access_token y tokens.account_id desde auth.json
Enviar una solicitud a https://chatgpt.com/backend-api/wham/usage
Incluir Authorization: Bearer ... y ChatGPT-Account-Id en los headers
Analizar las ventanas de cuota de cinco horas y semanal en la respuesta

Para qué sirve

Este enfoque es útil cuando quieres confirmar rápidamente:

cuánta cuota de cinco horas queda
cuánta cuota semanal queda
cuándo se reinicia la cuota

Si gestionas varias cuentas, el script también puede escanear account/*.auth.json e imprimir una tabla compacta de resumen. El archivo auth.json de la cuenta de ChatGPT con sesión iniciada suele encontrarse en ~/.codex/.

Entradas clave

En la práctica, el script depende principalmente de dos valores:

access_token
account_id

Ambos suelen estar disponibles en un auth.json local. Con ellos, los headers de la solicitud suelen tener este aspecto:

headers = {
    "Authorization": f"Bearer {auth_token}",
    "Accept": "application/json",
    "ChatGPT-Account-Id": auth_account_id,
    "Origin": "https://chatgpt.com",
    "Referer": "https://chatgpt.com/",
    "User-Agent": "Mozilla/5.0",
}

Cómo leer la respuesta

Cuando la solicitud funciona, las entradas más importantes son las dos ventanas de cuota:

five_hour
weekly

Un script práctico suele normalizarlas en:

porcentaje restante
hora de reinicio
duración de la ventana

También conviene admitir nombres alternativos de campos como primary_window, secondary_window, five_hour_limit y weekly_limit.

Problemas comunes

Una respuesta 401 normalmente significa que el access_token ha expirado o no es válido.

Una respuesta 403 normalmente significa que la cuenta no puede acceder a este endpoint, o que la cuenta está en un estado anómalo.

Si la respuesta usa nombres de campos inconsistentes, es mejor normalizarlos antes de imprimir el resumen.

Referencia

codex-auth-manager: https://github.com/RioArisk/codex-auth-manager

Código

import argparse
import base64
import json
import os
import sys
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any

import requests


UTC = timezone.utc
CST = timezone(timedelta(hours=8), name="CST")
JSONDict = dict[str, Any]


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Query ChatGPT Codex usage from /backend-api/wham/usage."
    )
    parser.add_argument(
        "account_name",
        nargs="?",
        help="Account name used to load account/<account_name>.auth.json. If omitted, load all *.auth.json files in account/.",
    )
    parser.add_argument(
        "--account-dir",
        default="account",
        help="Directory containing <account_name>.auth.json files.",
    )
    parser.add_argument(
        "--chatgpt-url",
        default="https://chatgpt.com/backend-api/wham/usage",
        help="ChatGPT usage endpoint.",
    )
    parser.add_argument(
        "--raw-json",
        action="store_true",
        help="Print the full JSON response body.",
    )
    parser.add_argument(
        "--raw-headers",
        action="store_true",
        help="Print response headers.",
    )
    return parser.parse_args()


def print_json(data: Any) -> None:
    print(json.dumps(data, indent=2, ensure_ascii=False))


def load_auth_json(path_str: str | Path | None) -> JSONDict | None:
    if not path_str:
        return None
    path = Path(path_str).expanduser()
    if not path.is_file():
        return None
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError):
        return None


def get_nested_string(data: JSONDict | None, *keys: str) -> str | None:
    current: Any = data
    for key in keys:
        if not isinstance(current, dict):
            return None
        current = current.get(key)
    return current if isinstance(current, str) and current else None


def format_dt(dt: datetime | None) -> str:
    if dt is None:
        return "-"
    return dt.astimezone(CST).strftime("%Y-%m-%d %H:%M:%S %Z")


def format_cst(dt: datetime | None) -> str:
    return format_dt(dt)


def epoch_ms_to_dt(value: Any) -> datetime | None:
    if value is None:
        return None
    try:
        raw = int(value)
    except (TypeError, ValueError):
        return None
    # Newer responses sometimes use epoch seconds, older ones use epoch milliseconds.
    timestamp = raw / 1000 if raw > 10**11 else raw
    return datetime.fromtimestamp(timestamp, tz=UTC)


def first_dict(data: Any, *keys: str) -> JSONDict | None:
    for key in keys:
        value = data.get(key) if isinstance(data, dict) else None
        if isinstance(value, dict):
            return value
    return None


def decode_jwt_exp(token: str) -> datetime | None:
    parts = token.split(".")
    if len(parts) != 3:
        return None
    try:
        payload = parts[1]
        payload += "=" * (-len(payload) % 4)
        data = json.loads(base64.urlsafe_b64decode(payload.encode("ascii")))
        exp = data.get("exp")
        if exp is None:
            return None
        return datetime.fromtimestamp(int(exp), tz=UTC)
    except (ValueError, TypeError, json.JSONDecodeError):
        return None


def get_percent_left(value: JSONDict) -> float | int | None:
    percent_left = value.get("percent_left")
    if percent_left is None:
        percent_left = value.get("remaining_percent")
    if percent_left is not None:
        return percent_left

    used_percent = value.get("used_percent")
    try:
        if used_percent is not None:
            return max(0, 100 - float(used_percent))
    except (TypeError, ValueError):
        return None
    return None


def resolve_limit_window(value: JSONDict) -> JSONDict:
    if (
        "reset_at" not in value
        and "reset_time_ms" not in value
        and isinstance(value.get("primary_window"), dict)
    ):
        return value["primary_window"]
    return value


def parse_limit_entry(name: str, value: Any) -> JSONDict | None:
    if not isinstance(value, dict):
        return None

    value = resolve_limit_window(value)

    percent_left = get_percent_left(value)
    reset_time_ms = value.get("reset_time_ms")
    if reset_time_ms is None:
        reset_time_ms = value.get("reset_at")

    window_seconds = value.get("limit_window_seconds")

    return {
        "name": name,
        "percent_left": percent_left,
        "reset_time_ms": reset_time_ms,
        "reset_at": epoch_ms_to_dt(reset_time_ms),
        "limit_window_seconds": window_seconds,
    }


def infer_limit_name(window_seconds: Any) -> str | None:
    if not isinstance(window_seconds, (int, float)):
        return None
    if window_seconds <= 6 * 3600:
        return "five_hour"
    if window_seconds >= 6 * 24 * 3600:
        return "weekly"
    return None


def relabel_rate_limits(primary: JSONDict | None, secondary: JSONDict | None) -> tuple[JSONDict | None, JSONDict | None]:
    for entry in (primary, secondary):
        if not entry:
            continue
        inferred_name = infer_limit_name(entry.get("limit_window_seconds"))
        if inferred_name:
            entry["name"] = inferred_name

    if primary and secondary and primary.get("name") == secondary.get("name"):
        if primary.get("name") == "weekly":
            primary["name"] = "five_hour"
        else:
            secondary["name"] = "weekly"

    if primary and primary.get("name") == "weekly" and secondary is None:
        return None, primary

    if secondary and secondary.get("name") == "five_hour" and primary is None:
        return secondary, None

    return primary, secondary


def parse_rate_limits(data: JSONDict) -> tuple[JSONDict | None, JSONDict | None]:
    primary = None
    secondary = None

    for primary_key in ("five_hour", "five_hour_limit", "five_hour_rate_limit", "primary"):
        if primary_key in data:
            primary = parse_limit_entry("five_hour", data.get(primary_key))
            if primary:
                break

    for secondary_key in ("weekly", "weekly_limit", "weekly_rate_limit", "secondary"):
        if secondary_key in data:
            secondary = parse_limit_entry("weekly", data.get(secondary_key))
            if secondary:
                break

    if primary is None:
        primary = parse_limit_entry("five_hour", data.get("primary_window"))
    if secondary is None:
        secondary = parse_limit_entry("weekly", data.get("secondary_window"))

    return relabel_rate_limits(primary, secondary)


def format_percent(value: Any) -> str:
    return f"{value:g}" if isinstance(value, (int, float)) else str(value if value is not None else "-")


def percent_sort_value(value: Any, descending: bool) -> tuple[int, float]:
    if isinstance(value, (int, float)):
        numeric_value = float(value)
        return (0, -numeric_value if descending else numeric_value)
    return (1, 0.0)


def get_auth_paths(account_dir: str, account_name: str | None) -> list[Path]:
    base_dir = Path(account_dir)
    if account_name:
        return [base_dir / f"{account_name}.auth.json"]
    return sorted(base_dir.glob("*.auth.json"))


def get_account_name_from_path(path: Path) -> str:
    suffix = ".auth.json"
    return path.name[: -len(suffix)] if path.name.endswith(suffix) else path.stem


def build_summary_row(account_name: str, five_hour: JSONDict | None, weekly: JSONDict | None) -> JSONDict:
    return {
        "account": account_name,
        "five_hour_percent": five_hour["percent_left"] if five_hour else None,
        "weekly_percent": weekly["percent_left"] if weekly else None,
        "weekly_reset_at": weekly["reset_at"] if weekly else None,
    }


def print_summary_rows(rows: list[JSONDict]) -> None:
    if not rows:
        return

    sorted_rows = sorted(
        rows,
        key=lambda row: (
            percent_sort_value(row.get("five_hour_percent"), descending=True),
            percent_sort_value(row.get("weekly_percent"), descending=True),
            format_cst(row.get("weekly_reset_at")),
            row["account"],
        ),
    )

    display_rows = []
    for row in sorted_rows:
        display_rows.append(
            {
                "account": str(row["account"]),
                "five_hour": format_percent(row.get("five_hour_percent")),
                "weekly": format_percent(row.get("weekly_percent")),
                "weekly_reset": format_cst(row.get("weekly_reset_at")),
            }
        )

    headers = {
        "account": "account",
        "five_hour": "five_hour%",
        "weekly": "weekly%",
        "weekly_reset": "weekly_reset",
    }
    widths = {
        key: max(len(headers[key]), max(len(item[key]) for item in display_rows))
        for key in headers
    }

    print(
        f"{headers['account']:<{widths['account']}}  "
        f"{headers['five_hour']:>{widths['five_hour']}}  "
        f"{headers['weekly']:>{widths['weekly']}}  "
        f"{headers['weekly_reset']:<{widths['weekly_reset']}}"
    )
    for item in display_rows:
        print(
            f"{item['account']:<{widths['account']}}  "
            f"{item['five_hour']:>{widths['five_hour']}}  "
            f"{item['weekly']:>{widths['weekly']}}  "
            f"{item['weekly_reset']:<{widths['weekly_reset']}}"
        )


def validate_token_inputs(
    token: str,
    account_id: str,
    auth_token: str | None,
    auth_account_id: str | None,
) -> int | None:
    if token.startswith("sess-"):
        print("status: invalid_token_type", file=sys.stderr)
        print(
            "message: --chatgpt-token looks like a session token (sess-...). Use the JWT access_token instead.",
            file=sys.stderr,
        )
        if auth_token:
            print(
                "hint: Found tokens.access_token in auth.json; omit --chatgpt-token or pass that value instead.",
                file=sys.stderr,
            )
        return 1

    token_exp = decode_jwt_exp(token)
    if token_exp is not None and token_exp <= datetime.now(UTC):
        print("status: expired", file=sys.stderr)
        print(f"message: access_token expired at {format_dt(token_exp)}", file=sys.stderr)
        if auth_token and auth_token != token:
            auth_token_exp = decode_jwt_exp(auth_token)
            hint = format_dt(auth_token_exp) if auth_token_exp else "unknown time"
            print(f"hint: auth.json contains a different access_token expiring at {hint}", file=sys.stderr)
        return 1

    if auth_account_id and account_id != auth_account_id:
        print("warning: supplied --account-id does not match auth.json tokens.account_id", file=sys.stderr)

    return None


def handle_error_response(response: requests.Response, data: Any, raw_json: bool) -> int | None:
    if response.status_code == 401:
        print("status: expired", file=sys.stderr)
        print("message: access_token expired or invalid", file=sys.stderr)
        if raw_json:
            print_json(data)
        return 3

    if response.status_code == 403:
        print("status: forbidden", file=sys.stderr)
        print("message: account has no access to this endpoint or is in an abnormal state", file=sys.stderr)
        if raw_json:
            print_json(data)
        return 3

    if response.status_code >= 400:
        print(f"HTTP {response.status_code}", file=sys.stderr)
        print_json(data)
        return 3

    return None


def fetch_chatgpt_usage(auth_path: Path, args: argparse.Namespace) -> tuple[int, JSONDict | None]:
    auth_data = load_auth_json(auth_path)
    account_name = get_account_name_from_path(auth_path)
    auth_token = get_nested_string(auth_data, "tokens", "access_token")
    auth_account_id = get_nested_string(auth_data, "tokens", "account_id")

    if not auth_data:
        print(f"{account_name}: auth file not found or invalid", file=sys.stderr)
        return 1, None

    if not auth_token:
        print(f"{account_name}: missing access_token", file=sys.stderr)
        return 1, None

    if not auth_account_id:
        print(f"{account_name}: missing account_id", file=sys.stderr)
        return 1, None

    validation_error = validate_token_inputs(
        auth_token,
        auth_account_id,
        auth_token,
        auth_account_id,
    )
    if validation_error is not None:
        return validation_error, None

    headers = {
        "Authorization": f"Bearer {auth_token}",
        "Accept": "application/json",
        "ChatGPT-Account-Id": auth_account_id,
        "Origin": "https://chatgpt.com",
        "Referer": "https://chatgpt.com/",
        "User-Agent": "Mozilla/5.0",
    }

    try:
        response = requests.get(args.chatgpt_url, headers=headers, timeout=60)
    except requests.RequestException as exc:
        print(f"Request failed: {exc}", file=sys.stderr)
        return 2, None

    if args.raw_headers:
        print("=== Headers ===")
        print_json(dict(response.headers))
        print()

    try:
        data = response.json()
    except ValueError:
        print(f"HTTP {response.status_code}", file=sys.stderr)
        print(response.text, file=sys.stderr)
        return 3, None

    error_response = handle_error_response(response, data, args.raw_json)
    if error_response is not None:
        return error_response, None

    if args.raw_json:
        print("=== Raw JSON ===")
        print_json(data)
        print()

    rate_limits = first_dict(data, "rate_limit", "rate_limits")

    if rate_limits is None:
        return 0, build_summary_row(account_name, None, None)

    five_hour, weekly = parse_rate_limits(rate_limits)
    return 0, build_summary_row(account_name, five_hour, weekly)


def main() -> None:
    args = parse_args()
    auth_paths = get_auth_paths(args.account_dir, args.account_name)
    if not auth_paths:
        print("No auth files found.", file=sys.stderr)
        sys.exit(1)

    exit_code = 0
    summary_rows: list[JSONDict] = []
    for auth_path in auth_paths:
        current_exit_code, summary_row = fetch_chatgpt_usage(auth_path, args)
        exit_code = max(exit_code, current_exit_code)
        if summary_row is not None and not args.raw_json:
            summary_rows.append(summary_row)

    if summary_rows:
        print_summary_rows(summary_rows)
    sys.exit(exit_code)


if __name__ == "__main__":
    main()

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.