Introducción al conjunto de datos de ejercicios: cómo instalar y utilizar el conjunto de datos de acciones de fitness 1324

Thu, 02 Jul 2026 08:15:18 +0800

hasaneyldrm/exercises-dataset es un proyecto de conjunto de datos para desarrolladores de aplicaciones de fitness. Organiza acciones de fitness en JSON estructurado y viene con dos páginas de inicio: index.html se usa para explorar acciones y setup.html se usa para ayudar a generar SQL de importación de bases de datos, ejemplos de llamadas a API y mensajes de desarrollo de back-end.

Según el proyecto README, el conjunto de datos actual cubre 1324 movimientos, incluidos nombres de movimientos, partes del cuerpo, equipos, músculos objetivo, grupos de músculos auxiliares e instrucciones paso a paso. El proyecto es adecuado para prototipos de aplicaciones de fitness, herramientas de planificación de entrenamiento, páginas de búsqueda de acciones, experimentos de sistemas de recomendación o como datos básicos al generar backends de API de fitness para modelos grandes.

Primero es necesario señalar un detalle: la introducción del almacén, README, setup.html y la descripción actual de data/exercises.json no son completamente consistentes. El archivo README indica claramente que las imágenes multimedia y los GIF no se distribuyen con el almacén; todavía hay una descripción antigua de “imágenes/vídeos incluidos” en setup.html; Los campos de ruta relativa como image y gif_url también pueden aparecer en el JSON sin formato actual. Al acceder realmente, deben prevalecer los archivos actuales en el almacén. No establezca de forma predeterminada que las imágenes y los archivos de animación deben estar disponibles.

¿Para qué escena es adecuada?

Este proyecto no es una aplicación de fitness completa, sino una base de datos que se puede conectar directamente a la aplicación. Puedes entenderlo en tres partes:

data/exercises.json: archivo de datos principal, que es lo que finalmente lee la aplicación.
index.html: herramienta de recuperación de acciones de la versión del navegador local, no se requiere backend.
setup.html: asistente de integración de desarrolladores, que proporciona creación de tablas de bases de datos, generación INSERT SQL, ejemplos de API y palabras de aviso de LLM.

Si solo desea ver rápidamente los datos, activar index.html es suficiente. Si desea incluir datos en su propio producto, debe comenzar con data/exercises.json y decidir si leer JSON directamente, importarlo a una base de datos o generar una API REST.

Instalación y descarga

La forma más sencilla es clonar el repositorio directamente:

1
2

git clone https://github.com/hasaneyldrm/exercises-dataset.git
cd exercises-dataset

El almacén en sí se compone principalmente de archivos estáticos, no requiere npm install y no tiene servicios de back-end que deban iniciarse. Una vez completada la clonación, el directorio será el siguiente:

exercises-dataset/
├── data/
│   └── exercises.json
├── index.html
├── setup.html
└── README.md

Si solo desea descargar el archivo de datos, también puede guardar el JSON sin formato directamente:

`1`	`curl -L -o exercises.json https://raw.githubusercontent.com/hasaneyldrm/exercises-dataset/main/data/exercises.json`

Windows PowerShell se puede descargar así:

1
2
3

Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/hasaneyldrm/exercises-dataset/main/data/exercises.json" `
  -OutFile "exercises.json"

Después de la descarga, se recomienda confirmar si el archivo se puede analizar normalmente:

`1`	`python -m json.tool data/exercises.json > /tmp/exercises.pretty.json`

Disponible en Windows:

`1`	`python -m json.tool .\data\exercises.json > .\exercises.pretty.json`

Si se informa un error en este paso, significa que la descarga del archivo está incompleta. Primero, vuelva a extraer el almacén o vuelva a descargar el JSON.

Abrir la herramienta del navegador localmente

El index.html del almacén es un navegador front-end puro que se puede abrir directamente:

# macOS
open index.html

# Windows PowerShell
Start-Process .\index.html

Es fantástico para comprobar rápidamente los datos de movimiento: busque nombres de movimientos, filtre por parte del cuerpo, máquina o músculo objetivo y haga clic en una tarjeta para ver las instrucciones. Debido a que el README ha declarado que los recursos multimedia no se distribuyen con el almacén, si la imagen o GIF está vacío al navegar, no significa que la carga de datos haya fallado.

Si el navegador restringe la lectura de archivos locales debido a políticas de seguridad, puede iniciar un servidor estático temporal en el directorio del almacén:

`1`	`python -m http.server 8000`

Entonces visita:

`1`	`http://localhost:8000/index.html`

Los usuarios de Node.js también pueden utilizar:

`1`	`npx serve .`

Luego presione la línea de comando para abrir la dirección local.

Utilice setup.html para generar ejemplos de bases de datos y API

setup.html es un asistente de integración para desarrolladores. El método de apertura es el mismo que index.html:

`1`	`python -m http.server 8000`

Entonces visita:

`1`	`http://localhost:8000/setup.html`

Su proceso consta principalmente de tres pasos.

El primer paso es la configuración de la base de datos. La página puede cambiar los tipos de bases de datos como SQL Server, PostgreSQL, MySQL, SQLite, etc., copiar la declaración CREATE TABLE correspondiente y generar un archivo INSERT SQL que contiene 1324 datos de acción. Este proceso de generación se completa localmente en el navegador y no requiere cargar datos.

El segundo paso es la integración API. Puede ingresar su propia URL base de API y la página generará ejemplos de llamadas en diferentes idiomas, incluidos cURL, JavaScript, Python, C#, Java, PHP y Go. Las interfaces de ejemplo incluyen:

1
2
3

GET /exercises/:id
GET /exercises?page=1&limit=20
GET /exercises?category=Strength&body_part=Chest

La interfaz aquí no es el servicio en línea que ya proporciona el almacén, sino la forma de interfaz que se recomienda implementar en su propio backend. En otras palabras, setup.html le ayuda a organizar los métodos de llamada y no iniciará la API por usted.

El tercer paso es Pregúntele a su LLM. Las páginas pueden generar mensajes basados en combinaciones de marcos y bases de datos, como Express.js + PostgreSQL, FastAPI + SQLite, Spring Boot + MySQL, ASP.NET Core + SQL Server, Laravel o Gin. Puede pegar las palabras clave en ChatGPT, Claude o Gemini y dejar que el modelo genere código de fondo basado en la estructura de datos.

Leer JSON directamente

Si su aplicación es pequeña, leer data/exercises.json directamente es la forma más rápida. Ejemplo de Python:

import json

with open("data/exercises.json", "r", encoding="utf-8") as f:
    exercises = json.load(f)

print("动作总数:", len(exercises))

chest = [item for item in exercises if item.get("category") == "chest"]
bodyweight = [item for item in exercises if item.get("equipment") == "body weight"]

print("胸部动作:", len(chest))
print("自重动作:", len(bodyweight))

first = exercises[0]
print(first["id"], first["name"])
print(first.get("instructions", {}).get("en"))

Ejemplo de Node.js:

const exercises = require("./data/exercises.json");

console.log("Total:", exercises.length);

const bodyweight = exercises.filter((item) => item.equipment === "body weight");
const byCategory = exercises.reduce((acc, item) => {
  const key = item.category || "unknown";
  acc[key] = acc[key] || [];
  acc[key].push(item);
  return acc;
}, {});

console.log("Bodyweight:", bodyweight.length);
console.log(Object.keys(byCategory));

En proyectos front-end, puedes poner JSON en public/data/exercises.json y luego usar fetch para cargar:

async function loadExercises() {
  const res = await fetch("/data/exercises.json");
  if (!res.ok) {
    throw new Error(`Failed to load exercises: ${res.status}`);
  }
  return await res.json();
}

loadExercises().then((exercises) => {
  console.log(exercises.length);
});

Si utiliza TypeScript, se recomienda definir primero un tipo conservador. Debido a las diferencias entre los campos README y JSON actuales, es mejor escribir campos como image, gif_url, media_id y instruction_steps como opcionales:

type Exercise = {
  id: string;
  name: string;
  category?: string;
  body_part?: string;
  equipment?: string;
  target?: string;
  muscle_group?: string;
  secondary_muscles?: string[];
  instructions?: Record<string, string>;
  instruction_steps?: Record<string, string[]>;
  media_id?: string | null;
  image?: string | null;
  gif_url?: string | null;
  created_at?: string;
};

De esta manera, incluso si el almacén ajusta los campos posteriormente, la aplicación no fallará fácilmente debido a la falta de un campo.

Cómo importar base de datos

Para proyectos formales, se recomienda importar datos a la base de datos. La razón es simple: la paginación, el filtrado, la búsqueda, la edición en segundo plano y el control de permisos de API son más fáciles de realizar.

Una estructura de tabla común se puede diseñar así:

CREATE TABLE exercises (
  id VARCHAR(32) PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  category VARCHAR(100),
  body_part VARCHAR(100),
  equipment VARCHAR(100),
  target VARCHAR(100),
  muscle_group VARCHAR(100),
  secondary_muscles JSON,
  instructions JSON,
  instruction_steps JSON,
  image VARCHAR(255),
  gif_url VARCHAR(255),
  media_id VARCHAR(100),
  created_at VARCHAR(64)
);

PostgreSQL puede cambiar el campo JSON a jsonb:

CREATE TABLE exercises (
  id text PRIMARY KEY,
  name text NOT NULL,
  category text,
  body_part text,
  equipment text,
  target text,
  muscle_group text,
  secondary_muscles jsonb,
  instructions jsonb,
  instruction_steps jsonb,
  image text,
  gif_url text,
  media_id text,
  created_at text
);

Se recomienda que el proceso de importación se realice en este orden:

Utilice setup.html para generar SQL de creación de tablas e INSERT SQL para la base de datos correspondiente.
Ejecute primero en la base de datos local o en la biblioteca de prueba, no importe directamente a la biblioteca de producción.
Comprueba si el número total de filas es igual a la longitud de la matriz JSON.
Índice de compilación: al menos agregue índices ordinarios a category, body_part, equipment, target.
Si desea realizar una búsqueda de palabras clave, considere la indexación de texto completo o servicios de búsqueda externos.

Por ejemplo, PostgreSQL puede agregar primero estos índices:

CREATE INDEX idx_exercises_category ON exercises(category);
CREATE INDEX idx_exercises_body_part ON exercises(body_part);
CREATE INDEX idx_exercises_equipment ON exercises(equipment);
CREATE INDEX idx_exercises_target ON exercises(target);

La API de backend puede implementar primero cuatro tipos de interfaces:

GET /exercises
GET /exercises/:id
GET /exercises?category=chest
GET /exercises?equipment=body%20weight

Se recomienda unificar los parámetros de paginación como:

`1`	`page=1&limit=20`

La estructura de respuesta puede permanecer estable:

{
  "items": [],
  "page": 1,
  "limit": 20,
  "total": 1324
}

Esto facilita el acceso a las listas de inicio, los filtros y el desplazamiento infinito.

Cómo lidiar con los recursos de los medios

El consejo README es importante: no utilice de forma predeterminada un repositorio que contenga imágenes de acción y GIF que estén directamente disponibles comercialmente. Afirma que los datos subyacentes provienen de EjercicioDB v1, los activos multimedia no se redistribuyen con el repositorio y algunos registros conservan referencias multimedia o rutas relativas.

Hay tres métodos de procesamiento en proyectos reales:

Utilice únicamente datos de texto, no muestre imágenes ni GIF.
Prepare usted mismo imágenes o videos de acción legalmente autorizados y luego use id o el nombre de la acción para establecer el mapeo.
Si tiene derecho a utilizar los recursos multimedia de EjercicioDB, acceda a la CDN o dirección de recursos correspondiente de acuerdo con los términos pertinentes.

No trate los campos image y gif_url directamente como “archivos que deben existir en el almacén”. Antes de acceder, deberás comprobar:

1
2

ls images
ls videos

Si el directorio no existe, la aplicación debe vaciar el área de medios u ocultar las entradas de imágenes y animaciones.

Escollos que son fáciles de pisar al acceder

Primero, los campos pueden cambiar. Los campos en el ejemplo README y JSON sin formato no son consistentes en todas partes, así que no haga que todos los campos sean obligatorios en su código. Especialmente los campos relacionados con los medios y los campos multilingües deben utilizar lecturas opcionales.

En segundo lugar, los valores categóricos están en estilo inglés en minúsculas, como chest, back, upper legs, body weight. Si su interfaz muestra chino, debe realizar una capa de mapeo en la aplicación:

const categoryLabel = {
  chest: "胸部",
  back: "背部",
  waist: "腰腹",
  "upper legs": "大腿",
  "upper arms": "上臂",
  shoulders: "肩部",
};

En tercer lugar, las instrucciones de acción no son consejos médicos. Es adecuado para su uso como prototipos de productos, contenido didáctico y datos de recuperación de acciones, pero los productos formales de fitness aún deben incluir consejos de seguridad, contraindicaciones y procesos de revisión profesional.

Cuarto, no ignore la fuente y la autorización. El archivo README explica la fuente de los datos subyacentes, los motivos de la no distribución de los medios y la declaración de derechos. EjercicioDB, rehospedaje de Kaggle y los términos de uso del almacén deben reconfirmarse antes del uso comercial.

Ruta recomendada

Si solo está haciendo una demostración, puede git clone directamente, abrir index.html y luego leer datos de data/exercises.json.

Si deseas realizar una solicitud de fitness completa, puedes proceder en este orden:

Clona el repositorio y fija una confirmación para evitar que cambios de campo posteriores afecten al proyecto.
Marque data/exercises.json para conocer la cobertura real de campos e idiomas.
Utilice setup.html para generar la base de datos SQL e importarla a la biblioteca de prueba.
Implementa /exercises, /exercises/:id, API de filtrado y paginación.
La interfaz muestra datos de texto y el área de medios primero se pone en cortocircuito.
Complemente sus propias imágenes, GIF o vídeos, sujeto a licencia.

La ventaja de este proceso es que es simple, controlable y no se verá afectado por problemas de autorización de los medios. La parte más valiosa de exercises-dataset es que organiza el conocimiento de las acciones de aptitud física en una estructura de datos que se puede leer y recuperar directamente; En cuanto a la visualización de medios, la lógica del plan de capacitación y las recomendaciones personalizadas, deben colocarse en su propia capa de aplicación para seguir mejorando.

API Development on KnightLi Blog