ModelScope AI：以 Streamlit 和 GitHub Actions 建構雲端 AI 儀錶板
De JSON a la nube: un dashboard de IA con Streamlit y GitHub Actions
Jefferson Vargas 開發 ModelScope AI，以 Python、Streamlit 和 Plotly 建構公開儀錶板，比較相同任務、語言及輸入格式下模型的精度、成本和延遲。
Elegir un modelo de inteligencia artificial para procesar documentos implica responder tres preguntas: ¿qué tan bien resuelve la tarea?, ¿cuánto cuesta? y ¿cuánto tarda?
Para explorar esas decisiones desarrollé ModelScope AI, un dashboard con Python, Streamlit y Plotly. La aplicación compara resultados de modelos dentro de una misma tarea, idioma y formato de entrada.
Enlaces del proyecto
- Código fuente y repositorio público: GitHub — iovargasjeff/ModelScope-AI.
- Aplicación desplegada en Streamlit Community Cloud: Abrir el dashboard ModelScope AI.
- Integración continua y actualización automatizada: GitHub Actions.
El dashboard se ejecuta públicamente en Streamlit Community Cloud, conectado al repositorio de GitHub. El primer despliegue se configura en la plataforma; después, la plataforma detecta cambios nuevos en la rama conectada. En las siguientes secciones explico el código, los datos y cómo se relacionan las automatizaciones.
1. Definir una pregunta que el dashboard pueda responder
La pregunta central del proyecto es:
Para una tarea, idioma y formato determinados, ¿qué relación existe entre precisión, costo y tiempo de respuesta de los modelos evaluados?
Esto determina el diseño de los filtros. Comparar un modelo evaluado sobre facturas con otro evaluado sobre contratos podría producir una conclusión engañosa. Por eso, primero se selecciona un grupo comparable de resultados y después se aplican los filtros de proveedor, modelo y rangos numéricos.
El dashboard sirve para explorar resultados publicados. No ejecuta consultas contra los modelos ni necesita una API key de un proveedor de IA para mostrar las comparaciones.
2. Seleccionar una fuente reutilizable y documentar sus límites
La aplicación utiliza el JSON público de ModelVerdict. Su página de datos publica los resultados bajo CC BY 4.0, con atribución. El proyecto conserva la referencia a la fuente y la licencia en sus datos y documentación.
Los resultados cubren tareas como extracción de facturas, clasificación de correos, detección de datos personales, extracción de términos contractuales, resumen y preguntas sobre documentos.
Estas son algunas de las variables utilizadas:
| Variable | Qué representa |
|---|---|
| Precisión por campo | Proporción de campos correctos |
| Documentos sin errores | Proporción de documentos completamente correctos |
| Costo por 1.000 documentos | Costo publicado, expresado en una unidad comparable |
| Latencia p50 | Mediana del tiempo de respuesta completo |
| Latencia p90 | Percentil 90 del tiempo de respuesta completo |
| Casos evaluados | Tamaño de la muestra del resultado |
Cada medición depende de las condiciones del benchmark. Antes de trasladar una conclusión a un proceso real, conviene consultar la metodología de ModelVerdict y validar con documentos propios. Tampoco se debe interpretar la latencia como tiempo al primer token o velocidad de generación: esas son métricas distintas.
El snapshot incluido en el repositorio identifica la ejecución publicada el 10 de octubre de 2026. Ese conjunto contiene 1.050 filas, 14 modelos, 7 proveedores y 75 cohortes de tarea, idioma y formato. Una fila describe el resultado de un modelo para una cohorte. La aplicación presenta la fecha y el estado de los datos para que sea posible distinguir el momento de evaluación de una actualización posterior del código.
El costo está normalizado por cada 1.000 documentos. Así, se puede comparar una escala práctica aunque una ejecución del benchmark haya usado menos documentos. La precisión por campo y la proporción de documentos sin errores responden preguntas diferentes: un documento puede tener varios campos correctos y todavía contener un error. Por eso, el dashboard deja elegir cuál de las dos métricas usar para algunas visualizaciones.
3. Separar datos, análisis y presentación
Organicé la aplicación en módulos para mantener las responsabilidades claras:
ModelScope-AI/
├── app.py # Interfaz de Streamlit
├── scripts/fetch_data.py # Descarga y actualización
├── src/
│ ├── data_loader.py # Lectura del snapshot
│ ├── data_processing.py # Validación y normalización
│ ├── metrics.py # KPIs y frontera de Pareto
│ ├── charts.py # Gráficos Plotly
│ └── theme.py # Apariencia clara y oscura
├── data/ # JSON, CSV y metadatos
├── tests/ # Pruebas de datos, métricas e interfaz
├── .github/workflows/ # CI y actualización programada
├── Dockerfile
└── docker-compose.yml
El recorrido de los datos es el siguiente:
JSON público → validación → normalización → CSV y metadatos
↓
Streamlit → Plotly
La aplicación lee una copia validada y versionada de los datos, conocida como snapshot. De esta manera, abrir el dashboard no requiere descargar el origen en cada interacción.
La separación también ayuda a depurar el proyecto. Si cambia el formato que publica la fuente, el contrato de datos se puede revisar en src/data_processing.py; las métricas viven en src/metrics.py; los componentes visuales se mantienen en src/charts.py; y app.py organiza la experiencia de usuario. Los tests se ubican en tests/, de modo que los cálculos puedan revisarse sin tener que inspeccionar el despliegue en la nube.
4. Construir la carga y transformación
El script scripts/fetch_data.py descarga el JSON y utiliza el módulo de normalización para convertir los resultados en filas de un DataFrame.
Antes de escribir los archivos, comprueba la licencia declarada, la estructura y los metadatos de la ejecución. También rechaza un resultado normalizado vacío. Si falla la descarga o la validación, conserva el snapshot anterior.
La salida contiene tres archivos principales:
-
leaderboards.json: respuesta original de la fuente. -
models.csv: tabla preparada para el análisis. -
metadata.json: identificación de la ejecución, fecha, origen y recuentos.
El script compara el run_id recibido con el guardado. Si la ejecución de origen ya está descargada y existen los archivos esperados, evita reescribirlos. Esto reduce commits que solo modificarían la fecha de descarga.
La actualización también puede ejecutarse manualmente:
python scripts/fetch_data.py
5. Crear una interfaz para explorar decisiones
Streamlit permite construir la interfaz desde Python. El punto de entrada configura una página amplia y carga el snapshot con caché:
st.set_page_config(
page_title="ModelScope AI | Model Performance Explorer",
page_icon="◈",
layout="wide",
initial_sidebar_state="auto",
)
@st.cache_data(ttl=300, show_spinner="Loading the latest validated snapshot…")
def get_snapshot():
return load_snapshot(DATA_DIR / "models.csv", DATA_DIR / "metadata.json")
Este fragmento resume la configuración utilizada en app.py.
La interfaz ofrece filtros de tarea, idioma, formato, proveedor y modelo. Los rangos de precisión, costo y latencia permiten explorar restricciones concretas: por ejemplo, buscar alternativas que cumplan un nivel mínimo de precisión dentro de un presupuesto.
Cuatro tarjetas resumen los modelos y proveedores seleccionados, la mediana del costo y la mediana de la latencia p50. Este último indicador es una mediana entre resultados de modelos; no equivale al p50 de todas las solicitudes del benchmark combinadas.
También incorporé controles de modo claro y oscuro, colores consistentes por proveedor y una tabla con selección de orden. La exportación CSV permite continuar el análisis fuera de la aplicación.
La barra lateral empieza con los filtros de tarea, idioma y formato. Después permite elegir la medida de precisión, proveedores y modelos específicos. El cuadro de búsqueda ayuda a localizar un modelo por nombre, mientras que el grupo desplegable de rangos independientes sirve para acotar precisión, costo y velocidad. Si no se selecciona ningún modelo en particular, el tablero conserva todos los que pertenecen a la cohorte.
Las tarjetas KPI muestran el número de modelos y proveedores que quedan luego de aplicar los filtros, junto con la mediana del costo y la mediana de latencia p50. El cálculo ocurre después de filtrar. Esto importa: si se excluyen modelos caros, la mediana debe describir la selección nueva y no el conjunto original.
El tema claro u oscuro se aplica de forma coordinada a los controles, las tablas y los gráficos de Plotly. Los colores de proveedor se mantienen consistentes entre las vistas para que reconocer una misma familia no requiera leer cada leyenda de nuevo. En pantallas más pequeñas, las tarjetas resumen se redistribuyen para que el usuario pueda consultar el estado de los filtros sin perder el contexto.
6. Mostrar las compensaciones con Plotly
El gráfico principal relaciona precisión y costo. Cada punto representa un modelo dentro del grupo seleccionado; el detalle interactivo permite consultar información adicional sin saturar la vista.
La frontera de Pareto destaca alternativas para las que no existe otra opción con precisión igual o superior y costo igual o inferior, con mejora estricta en al menos una de esas dimensiones.
Por ejemplo, en un caso hipotético:
| Modelo | Precisión | Costo por 1.000 documentos |
|---|---|---|
| A | 95 % | USD 1,00 |
| B | 95 % | USD 2,00 |
| C | 98 % | USD 3,00 |
B está dominado por A: entrega la misma precisión a mayor costo. A y C representan dos decisiones posibles según el presupuesto y la precisión requerida.
La implementación está en src/metrics.py. La frontera se calcula sobre el conjunto mostrado después de los filtros y considera únicamente precisión y costo. Para decidir también por velocidad, hay que revisar los gráficos de latencia.
El dashboard complementa esta vista con comparaciones de proveedores, ordenamiento de costos y visualizaciones de p50 y p90. La mediana por proveedor resume los modelos presentes en la selección; puede cambiar cuando cambia esa selección.
En el gráfico de dispersión, cada punto es un modelo. El color indica su proveedor y la interacción de hover muestra precisión, costo, latencia p50 y p90, cantidad de casos y error más común cuando la fuente lo publica. Las estrellas resaltan las opciones que están en la frontera. Ver varios puntos eficientes a la vez es útil: indica que se puede escoger según el presupuesto o la precisión requerida, en vez de buscar un único ganador.
La pestaña de costos ordena modelos de mayor a menor o de menor a mayor, y permite escoger cuántos mostrar. Las pestañas de velocidad separan la relación precisión/latencia p50 del diagrama p50/p90. Este segundo gráfico permite ver si una mediana rápida viene acompañada de una cola de respuestas lentas. El análisis de proveedores muestra costos medianos y una tabla con precisión y latencia. La pestaña de comparación permite poner entre dos y cuatro modelos lado a lado; el explorador tabular permite ordenar cualquier columna y descargar el resultado filtrado como CSV.
El archivo exportado mantiene campos de origen y licencia. Esto es deliberado: un CSV que se comparte fuera del dashboard debe seguir acompañado de la atribución a ModelVerdict y de información sobre el conjunto del que proviene.
Un ejemplo con el snapshot del repositorio
Para ilustrar la lectura, tomé la cohorte predeterminada del snapshot: facturas en inglés, todos los formatos, 14 modelos y 150 casos por modelo. En esa muestra, la frontera de Pareto de precisión por campo y costo contiene tres puntos:
| Modelo | Precisión por campo | Documentos sin errores | Costo / 1.000 documentos | Latencia p50 |
|---|---|---|---|---|
| Gemma 4 31B | 97,64 % | 81,33 % | USD 0,1675 | 8,869 s |
| GPT-6 Luna | 99,70 % | 96,67 % | USD 0,5074 | 3,435 s |
| Claude Haiku 5.5 | 100,00 % | 100,00 % | USD 0,6062 | 3,393 s |
Gemma 4 31B es la opción menos costosa de esas tres, pero sus tiempos y precisión son distintos de los otros dos puntos. Claude Haiku 5.5 alcanza la mayor precisión de esta muestra, y GPT-6 Luna se sitúa entre ambos en costo y precisión. Ninguno domina a los otros simultáneamente en precisión y costo; por eso los tres permanecen en la frontera.
En los 14 modelos de la cohorte, la mediana del costo es USD 1,04985 por 1.000 documentos y la mediana de p50 es 3,4885 segundos. Son estadísticas de este snapshot y esta tarea, no una recomendación universal ni un pronóstico de costos de producción. Una actualización del origen puede modificar los valores; para consultarlos en vivo, abre el dashboard publicado y revisa el estado de los datos.
7. Ejecutar el proyecto en local con Python o Docker
Para reproducir el entorno con Python:
git clone https://github.com/iovargasjeff/ModelScope-AI.git
cd ModelScope-AI
python -m venv .venv
En Windows PowerShell, activa el entorno con:
.\.venv\Scripts\Activate.ps1
En Linux o macOS:
source .venv/bin/activate
Después instala las dependencias y ejecuta la aplicación:
pip install -r requirements-dev.txt
streamlit run app.py
El repositorio incluye un snapshot para comenzar. Para buscar datos más recientes se puede ejecutar el script de actualización antes de iniciar Streamlit.
La alternativa con Docker es:
docker compose up --build
La aplicación queda disponible en http://localhost:8501. Docker facilita la ejecución local reproducible; el despliegue público de este proyecto utiliza la integración de Streamlit Community Cloud con GitHub.
El Dockerfile parte de Python 3.12 slim, instala las dependencias de ejecución y copia la aplicación, módulos y datos del snapshot. El contenedor usa un usuario sin privilegios, publica el puerto 8501 y tiene un chequeo de salud contra el endpoint interno de Streamlit. Docker sirve para comprobar que el proyecto inicia en un entorno aislado parecido al de un servidor; no reemplaza al proveedor donde se hospeda la URL pública.
8. Automatizar las comprobaciones y la actualización de datos
El proyecto tiene dos workflows con responsabilidades diferentes.
Integración continua
El archivo ci.yml se ejecuta en pushes y pull requests dirigidos a main, y permite ejecución manual. Prepara Python 3.12, instala dependencias y ejecuta:
ruff check app.py src scripts tests
pytest -q
python -m compileall -q app.py src scripts
Las pruebas cubren normalización, cálculos y comportamiento de la interfaz mediante AppTest, además de los gráficos. Las ejecuciones se pueden revisar en GitHub Actions.
Actualización programada
El archivo update-data.yml consulta el origen diariamente y también admite ejecución manual. Ejecuta lint y pruebas antes de descargar y validar los datos. Si hay cambios en el snapshot, crea un commit y lo envía al repositorio.
Consultar diariamente no significa que la fuente publique nuevos resultados cada día. La identificación de la ejecución permite distinguir una nueva medición de una consulta repetida.
El flujo diario se puede resumir así:
GitHub Actions (cada día)
↓
lint + pruebas → descargar JSON → validar licencia y esquema
↓
¿run_id nuevo? ── no ──→ no hay commit
│
sí
↓
actualizar JSON + CSV + metadatos → commit de bot a main
El workflow usa GITHUB_TOKEN con permiso de contenido para versionar el resultado; no hay una clave privada de un proveedor de IA ni una API key adicional de ModelVerdict. La copia inicial de los datos está versionada, así que la aplicación también tiene información que cargar si el workflow no se ha ejecutado desde que se publicó el proyecto.
9. Publicar en la nube y automatizar los siguientes despliegues
La aplicación pública está disponible en modelscope-ai.streamlit.app.
La conexión inicial en Streamlit Community Cloud utiliza estos parámetros:
- Repositorio:
iovargasjeff/ModelScope-AI. - Rama:
main. - Archivo de entrada:
app.py. - Dependencias:
requirements.txt.
Se puede abrir Streamlit Community Cloud, elegir Create app y apuntar a ese repositorio, rama y archivo de entrada. En el repositorio público, las librerías de ejecución se leen de requirements.txt; requirements-dev.txt agrega herramientas de desarrollo como pytest y ruff.
Después de conectar el repositorio, Community Cloud actualiza la aplicación cuando recibe cambios en la rama vinculada. Este comportamiento está descrito en la documentación oficial de gestión de aplicaciones.
El flujo completo queda así:
Cambio de código o snapshot → commit en main
├── GitHub Actions: comprobaciones de CI
└── Community Cloud: actualización de la app
La conexión inicial requiere configuración en la plataforma; las actualizaciones posteriores son automáticas. El workflow de CI no ejecuta un comando de despliegue ni actúa por sí solo como barrera que impida publicar cuando una prueba falla. Para exigir comprobaciones antes de integrar código sería necesario configurar protecciones de rama y trabajar mediante pull requests.
La secuencia para un cambio de aplicación queda así: se publica el commit en main, GitHub Actions ejecuta los chequeos definidos por el proyecto y Streamlit Community Cloud recibe el cambio de la rama conectada para reconstruir la aplicación. La configuración de GitHub Actions y la integración de despliegue son piezas relacionadas, pero independientes: en este repositorio, las pruebas y el despliegue no están unidos por un workflow de publicación personalizado. Esta distinción permite explicar con precisión qué se automatizó y qué debe comprobar una persona antes de integrar un cambio.
La página de la app es el lugar para probar la experiencia final. El código, la configuración, las dependencias, el snapshot y los workflows se pueden consultar en el repositorio público; la app servida al público está en Streamlit Community Cloud. Si necesitas reconstruirla o auditarla, revisa también la documentación de despliegue de Streamlit y la documentación sobre actualizaciones.
10. Demostración en video
La demostración del proyecto debe mostrar la selección de una tarea, la interacción con los filtros, los gráficos y el recorrido desde el repositorio hasta la aplicación desplegada. El repositorio incluye un guion de grabación de menos de cinco minutos.
Conclusión
ModelScope AI reúne carga de datos, análisis y visualización en una aplicación pública que se puede reproducir desde su repositorio. Streamlit construye la experiencia interactiva, Plotly permite explorar las mediciones y GitHub mantiene el código y los datos versionados.
La decisión central del proyecto es mantener cada comparación dentro de las mismas condiciones de evaluación. Una visualización resulta más útil cuando sus métricas, unidades y límites están claros: permite entender qué se gana en precisión, qué cuesta y cuánto tiempo requiere.
Este proyecto recorre la ruta completa de un dashboard de datos: una fuente pública con licencia, validación y normalización en Python, métricas calculadas dentro de cohortes comparables, gráficos interactivos y una app publicada que sigue el repositorio. La automatización diaria comprueba si existe una versión nueva de los datos y GitHub Actions mantiene pruebas y linting en el flujo de desarrollo. Docker complementa ese proceso con una forma repetible de ejecutar localmente.
Puedes explorar el dashboard o consultar y reproducir el código.
Atribución: datos de ModelVerdict, bajo CC BY 4.0. El proyecto transforma y visualiza los resultados publicados. Este artículo y la aplicación son análisis independientes y no implican respaldo de ModelVerdict.
來源：DEV Community · dev.to