# Guía de Solución de Problemas para AI-For-Beginners Esta guía te ayuda a resolver problemas comunes al usar o contribuir al repositorio [AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners). Cada problema incluye antecedentes, síntomas, explicaciones y soluciones paso a paso. --- ## Tabla de Contenidos - [Problemas Generales](../..) - [Problemas de Instalación](../..) - [Problemas de Configuración](../..) - [Ejecutar Notebooks](../..) - [Problemas de Rendimiento](../..) - [Problemas del Sitio Web del Libro](../..) - [Problemas al Contribuir](../..) - [Preguntas Frecuentes](../..) - [Obtener Ayuda](../..) --- ## Problemas Generales ### 1. El repositorio no se clona correctamente **Antecedentes:** Clonar permite copiar el repositorio a tu máquina. **Síntomas:** - Error: `fatal: repository not found` - Error: `Permission denied (publickey)` **Posibles Causas:** - URL del repositorio incorrecta - Permisos insuficientes - Claves SSH no configuradas **Soluciones:** 1. **Verifica la URL del repositorio.** Usa la URL HTTPS: ``` git clone https://github.com/microsoft/AI-For-Beginners.git ``` 2. **Cambia a HTTPS si falla SSH.** Si ves `Permission denied (publickey)`, usa el enlace HTTPS mencionado en lugar de SSH. 3. **Configura claves SSH (opcional).** Si prefieres usar SSH, sigue la [guía de SSH de GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). --- ## Problemas de Instalación ### 2. Problemas con el entorno de Python **Antecedentes:** El repositorio depende de Python y varias bibliotecas. **Síntomas:** - Error: `ModuleNotFoundError: No module named ''` - Errores de importación al ejecutar scripts o notebooks **Posibles Causas:** - Dependencias no instaladas - Versión incorrecta de Python **Soluciones:** 1. **Configura un entorno virtual.** ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 2. **Instala las dependencias.** ```bash pip install -r requirements.txt ``` 3. **Verifica la versión de Python.** Usa Python 3.7 o más reciente. ```bash python --version ``` ### 3. Jupyter no está instalado **Antecedentes:** Los notebooks son un recurso clave de aprendizaje. **Síntomas:** - Error: `jupyter: command not found` - Los notebooks no se abren **Posibles Causas:** - Jupyter no está instalado **Soluciones:** 1. **Instala Jupyter Notebook.** ```bash pip install notebook ``` o, si usas Anaconda: ```bash conda install notebook ``` 2. **Inicia Jupyter Notebook.** ```bash jupyter notebook ``` ### 4. Conflictos de versiones de dependencias **Antecedentes:** Los proyectos pueden fallar si las versiones de los paquetes no coinciden. **Síntomas:** - Errores o advertencias sobre versiones incompatibles **Posibles Causas:** - Paquetes de Python antiguos o en conflicto **Soluciones:** 1. **Instala en un entorno limpio.** Elimina el entorno venv/conda antiguo y crea uno nuevo. 2. **Usa versiones exactas.** Siempre ejecuta: ```bash pip install -r requirements.txt ``` Si esto falla, instala manualmente los paquetes faltantes como se describe en el README. --- ## Problemas de Configuración ### 5. Variables de entorno no configuradas **Antecedentes:** Algunos módulos pueden requerir claves, tokens o configuraciones. **Síntomas:** - Error: `KeyError` o advertencias sobre configuraciones faltantes **Posibles Causas:** - Variables de entorno requeridas no configuradas **Soluciones:** 1. **Busca archivos como `.env.example` o similares.** 2. **Crea un archivo `.env` y completa los valores requeridos.** 3. **Recarga tu terminal o IDE después de configurar las variables de entorno.** --- ## Ejecutar Notebooks ### 6. El notebook no se abre o no se ejecuta **Antecedentes:** Los notebooks de Jupyter necesitan una configuración adecuada. **Síntomas:** - El notebook no se lanza - El navegador no se abre automáticamente **Posibles Causas:** - Jupyter no está instalado - Problemas de configuración del navegador **Soluciones:** 1. **Instala Jupyter (ver Problemas de Instalación arriba).** 2. **Abre los notebooks manualmente.** - Copia la URL desde el terminal (por ejemplo, `http://localhost:8888/?token=...`) y pégala en tu navegador. ### 7. El kernel se bloquea o se congela **Antecedentes:** Los kernels de los notebooks pueden fallar debido a límites de recursos o errores de código. **Síntomas:** - El kernel muere o se reinicia repetidamente - Errores de memoria insuficiente **Posibles Causas:** - Conjuntos de datos grandes - Código o paquetes incompatibles **Soluciones:** 1. **Reinicia el kernel.** Usa el botón "Restart Kernel" en Jupyter. 2. **Verifica el uso de memoria.** Cierra aplicaciones no utilizadas. 3. **Ejecuta los notebooks en plataformas en la nube.** Usa [Google Colab](https://colab.research.google.com/) o [Azure Notebooks](https://notebooks.azure.com/). --- ## Problemas de Rendimiento ### 8. Los notebooks se ejecutan lentamente **Antecedentes:** Algunas tareas de IA requieren mucha memoria y CPU. **Síntomas:** - Ejecución lenta - El ventilador del portátil funciona a alta velocidad **Posibles Causas:** - Conjuntos de datos o modelos grandes - Recursos limitados del sistema **Soluciones:** 1. **Usa una plataforma en la nube.** - Sube el notebook a Colab o Azure Notebooks. 2. **Reduce el tamaño del conjunto de datos.** - Usa datos de muestra para practicar. 3. **Cierra programas innecesarios.** - Libera RAM del sistema. --- ## Problemas del Sitio Web del Libro ### 9. El capítulo no se carga **Antecedentes:** El libro en línea muestra lecciones y capítulos. **Síntomas:** - Un capítulo (por ejemplo, Transformers/BERT) falta o no se abre **Problema Conocido:** - [Problema #303](https://github.com/microsoft/AI-For-Beginners/issues/303): “18 Transformers. BERT. no se puede abrir en el sitio web del libro.” Causado por un error en el nombre del archivo (`READMEtransformers.md` en lugar de `README.md`). **Soluciones:** 1. **Verifica errores en el renombrado de archivos.** Si eres un contribuyente, asegúrate de que los archivos de los capítulos se llamen `README.md`. 2. **Reporta archivos faltantes.** Abre un problema en GitHub con el nombre del capítulo y detalles del error. --- ## Problemas al Contribuir ### 10. PR no aceptado o fallos en las compilaciones **Antecedentes:** Las contribuciones deben pasar pruebas y seguir las pautas. **Síntomas:** - Pull request rechazado - Errores en la canalización CI/CD **Posibles Causas:** - Pruebas fallidas - No seguir los estándares de codificación **Soluciones:** 1. **Lee las pautas de contribución.** - Sigue el [CONTRIBUTING.md](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) del repositorio. 2. **Ejecuta pruebas localmente antes de hacer push.** 3. **Verifica reglas de linting o requisitos de formato.** --- ## Preguntas Frecuentes ### ¿Dónde puedo encontrar ayuda para módulos específicos? - Cada módulo generalmente tiene su propio README. Comienza allí para obtener consejos de configuración y uso. ### ¿Cómo reporto un error o solicito una función? - [Abre un problema en GitHub](https://github.com/microsoft/AI-For-Beginners/issues/new) con una descripción clara y pasos para reproducir. ### ¿Puedo pedir ayuda si mi problema no está listado? - ¡Sí! Busca problemas existentes primero, y si no encuentras tu problema, crea uno nuevo. --- ## Obtener Ayuda - **Revisa Problemas:** [Problemas en GitHub](https://github.com/microsoft/AI-For-Beginners/issues) - **Haz Preguntas:** Usa las discusiones de GitHub o abre un problema. - **Comunidad:** Consulta los enlaces del repositorio para opciones de chat/foro. --- _Última Actualización: 20 de septiembre de 2025_ --- **Descargo de responsabilidad**: Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por garantizar la precisión, tenga en cuenta que las traducciones automáticas pueden contener errores o imprecisiones. El documento original en su idioma nativo debe considerarse como la fuente autorizada. Para información crítica, se recomienda una traducción profesional realizada por humanos. No nos hacemos responsables de malentendidos o interpretaciones erróneas que puedan surgir del uso de esta traducción.