Aprovechando las Capacidades de IA Local de ServBay: Traduce Documentos Markdown en Lote sin Esfuerzo

Dheeraj MalhotraDheeraj Malhotra
26 min read

Introducción

En el mundo cada vez más globalizado de hoy, la demanda de contenido multilingüe está explotando. Ya sea documentación técnica, publicaciones de blog, informes de investigación o notas personales, traducirlos a diferentes idiomas puede expandir significativamente su audiencia e impacto. Sin embargo, los métodos de traducción tradicionales, como la traducción manual, son costosos y consumen mucho tiempo. Usar servicios de traducción en línea (como Google Translate, DeepL, etc.) podría implicar preocupaciones sobre la privacidad de los datos, tarifas de llamadas API y limitaciones de conectividad de red.

Para desarrolladores, creadores de contenido y entusiastas de la tecnología que buscan eficiencia, privacidad de datos y rentabilidad, ¿existe una forma de realizar traducciones por lotes de alta calidad localmente, sin conexión y a bajo costo? ¡La respuesta es sí! Con la maduración y popularización de la tecnología de Modelos de Lenguaje Grandes (LLM) locales, ahora podemos ejecutar potentes modelos de IA en nuestras propias computadoras para realizar diversas tareas, incluida la traducción de textos.

Y para los usuarios de ServBay, esto se vuelve aún más simple e integrado. ServBay, como un potente entorno de desarrollo web integrado, no solo proporciona una gestión conveniente de servidores web, bases de datos y entornos de lenguaje, sino que su última versión también se mantiene al día con las tendencias tecnológicas al incorporar soporte integrado para IA/LLM, integrando específicamente el popular framework Ollama. Esto significa que puedes implementar y gestionar fácilmente modelos de IA locales dentro del entorno ServBay sin configuraciones complejas y aprovechar sus potentes capacidades.

Este tutorial, basado en ServBay, te guiará en detalle sobre cómo:

  1. Comprender el último soporte de IA/LLM de ServBay, particularmente sus características integradas de Ollama.

  2. Instalar y configurar fácilmente el servicio Ollama dentro de ServBay.

  3. Buscar, descargar y gestionar modelos Ollama adecuados para tareas de traducción a través de la interfaz gráfica de ServBay.

  4. Escribir un script de Python que utilice el endpoint de la API de Ollama proporcionado por ServBay para automatizar la traducción por lotes de todos los archivos Markdown (.md) dentro de una carpeta especificada (por ejemplo, docs).

A través de este tutorial, dominarás una solución de traducción de documentos local potente, privada y eficiente, liberando todo el potencial de ServBay y la IA local. ¡Embárquemonos en este emocionante viaje de IA local!

Descripción de la imagen

Parte 1: La Nueva Era de IA / LLM de ServBay: Abrazando la Inteligencia Local

ServBay siempre se ha comprometido a proporcionar a los desarrolladores un entorno de desarrollo local integral, eficiente y conveniente. Desde la gestión de múltiples versiones de PHP, Python, Java, .Net, Node.js, el cambio entre Nginx/Apache/Caddy, hasta el soporte de bases de datos MySQL/PostgreSQL/MongoDB, ServBay simplifica enormemente la configuración y el mantenimiento de los entornos de desarrollo. Ahora, ServBay está una vez más a la vanguardia, integrando potentes capacidades de IA/LLM en sus características principales, abriendo un nuevo capítulo de inteligencia local para sus usuarios.

Integrando Ollama: La Navaja Suiza para LLMs Locales

El núcleo de la funcionalidad de IA de ServBay es la integración de Ollama. Ollama es un proyecto de código abierto diseñado para permitir a los usuarios ejecutar fácilmente modelos de lenguaje grandes como Llama 3, Mistral, Phi-3, Gemma3, etc., localmente. Simplifica significativamente el proceso de configuración, ejecución y gestión de modelos, proporcionando una interfaz API estándar que permite a los desarrolladores interactuar con modelos locales tan convenientemente como llamar a servicios en la nube.

La integración de Ollama en ServBay aporta numerosas ventajas:

  • Instalación y Configuración con un Clic: ServBay proporciona una interfaz gráfica dedicada para gestionar Ollama. Los usuarios no necesitan descargar manualmente Ollama, configurar variables de entorno o gestionar dependencias complejas. Simplemente habilítalo y configúralo brevemente en el panel de IA de ServBay, y tendrás un servicio LLM local listo para usar.

  • Gestión Visual de la Configuración: ServBay ofrece ricas opciones de configuración, como Model Download Threads (Hilos de Descarga de Modelos), Bind IP, Bind Port (por defecto 127.0.0.1:11434, la configuración estándar de Ollama), interruptores de depuración (Debug, Flash Attention, No History, No Prune, Schedule Spread, Multi-user Cache), tipo de caché (K/V Cache Type), optimización de GPU (GPU Overhead), persistencia de conexión (Keepalive), tiempo de espera de carga (Load Timeout), modelos máximos cargados (Max loaded models), cola máxima (Max Queue), número de procesamiento paralelo (Parallel Num.), ruta de la biblioteca LLM (LLM Library), ruta de almacenamiento de modelos (Models folder), y control de origen de acceso (origins). Esto permite a los usuarios ajustar finamente los parámetros de ejecución de Ollama según su hardware y necesidades sin memorizar argumentos de línea de comandos.

  • Ecosistema Unificado: Integrar Ollama en ServBay significa que tu entorno de desarrollo web y tu entorno de inferencia de IA pueden trabajar juntos bajo la misma plataforma de gestión. Esto proporciona una gran comodidad para desarrollar aplicaciones web que requieren funciones de IA (como servicio al cliente inteligente, generación de contenido, análisis de datos locales, etc.).

Gestión Conveniente de Modelos

Solo tener un framework en ejecución no es suficiente; seleccionar y gestionar los modelos de IA apropiados es igualmente importante. ServBay también sobresale en esta área:

  • Listado y Búsqueda de Modelos: ServBay proporciona una interfaz de lista de modelos donde los usuarios pueden buscar directamente modelos disponibles en la biblioteca oficial de modelos de Ollama (por ejemplo, la captura de pantalla muestra la búsqueda de deeps mostrando diferentes versiones de deepseek-r1).

  • Descarga y Eliminación con un Clic: Para los modelos buscados, la interfaz muestra claramente el nombre del modelo (incluyendo etiquetas como latest, 1.5b, 7b, etc.), el modelo base, el número de parámetros (Parameters), el tamaño del archivo (File Size), y los botones de acción (descargar + o eliminar). Los usuarios simplemente hacen clic en un botón, y ServBay maneja automáticamente la descarga y el almacenamiento del modelo (la ruta de almacenamiento se puede especificar en la configuración de Ollama, por defecto /Applications/ServBay/db/ollama/models).

  • Vista General de Modelos Locales: En la interfaz Ollama Config (primera captura de pantalla), la lista del lado izquierdo muestra los modelos actualmente descargados localmente (por ejemplo, alfred, all-minilm, codellama, etc.). Esto da a los usuarios una visión general clara de los "cerebros" de IA local que poseen.

Valor Fundamental de la IA Local

¿Por qué usar IA local (a través de Ollama en ServBay) para la traducción en lugar de continuar con los servicios en línea?

  • Privacidad y Seguridad de Datos: Esta es la ventaja más crucial. Todo el procesamiento de datos se realiza en tu propia computadora; el contenido de tus documentos no necesita ser enviado a ningún servidor de terceros. Esto es esencial para documentos que contienen información sensible o secretos comerciales.

  • Rentabilidad: Ejecutar LLMs localmente no incurre en tarifas de llamadas API. Si bien puede haber una inversión inicial en hardware (especialmente si se necesita aceleración por GPU), el costo a largo plazo para tareas grandes o frecuentes es mucho menor que los servicios en la nube de pago por uso.

  • Disponibilidad sin Conexión: Una vez que un modelo se descarga localmente, puedes realizar traducciones u otras tareas de IA sin conexión a internet, lo cual es muy útil en entornos con redes inestables o escenarios que requieren una operación completamente fuera de línea.

  • Personalización y Control: Tienes la libertad de elegir el modelo que mejor se adapte a tu tarea y hardware, experimentar con diferentes versiones y parámetros del modelo, e incluso realizar ajustes finos (fine-tuning) (aunque ServBay en sí mismo no proporciona directamente funciones de ajuste fino, el entorno Ollama localizado sienta las bases para ello).

  • Baja Latencia: Las solicitudes se envían directamente al servicio que se ejecuta localmente, lo que generalmente resulta en una latencia más baja y respuestas más rápidas en comparación con llamar a API remotas a través de internet.

En resumen, al integrar Ollama, ServBay reduce significativamente la barrera para que los usuarios utilicen modelos de lenguaje grandes locales, incorporando sin problemas sus potentes capacidades de IA en un entorno de desarrollo familiar, proporcionando una base sólida para implementar tareas de automatización avanzadas como la traducción de documentos por lotes.

Descripción de la imagen

Parte 2: Instalación y Configuración de Ollama y Modelos en ServBay

Ahora, veamos paso a paso cómo configurar el servicio Ollama en ServBay y descargar un modelo adecuado para tareas de traducción.

Paso 1: Navegar a la Configuración de IA de ServBay

  1. Inicia la aplicación ServBay.

  2. En la barra de navegación izquierda de la interfaz principal de ServBay, busca y haz clic en AI.

  3. En el submenú de IA, haz clic en Ollama. Deberías ver una interfaz similar a la Ollama Config mostrada en la primera captura de pantalla.

Paso 2: Comprobar y (Opcionalmente) Ajustar la Configuración de Ollama

ServBay generalmente proporciona un conjunto razonable de configuraciones predeterminadas, a menudo suficientes para el uso inicial o tareas básicas. Sin embargo, comprender estas opciones ayuda con la optimización futura:

  • Estado del Servicio Ollama: Generalmente hay un interruptor de palanca o un indicador de estado en la parte superior de la interfaz (un punto verde en la captura de pantalla). Asegúrate de que el servicio Ollama esté habilitado. Si ServBay proporciona botones de Inicio/Parada, asegúrate de que esté en ejecución.

  • Bind IP y Bind Port: Los valores predeterminados 127.0.0.1 y 11434 son configuraciones estándar, lo que significa que el servicio Ollama solo escucha solicitudes de la máquina local en el puerto 11434. Esta es la dirección a la que nuestro script de Python necesitará conectarse más tarde. Generalmente, no se necesitan cambios.

  • Carpeta de Modelos (Models folder): Esta es la ruta donde se almacenan los modelos LLM descargados. La captura de pantalla muestra /Applications/ServBay/db/ollama/models. Puedes cambiar esto a otra ubicación con suficiente espacio en disco si es necesario, pero asegúrate de que la ruta exista y ServBay tenga permisos de escritura. Toma nota de esta ruta; aunque el script no la usa directamente, saber dónde están los modelos es útil.

  • Hilos de Descarga de Modelos (Model Download Threads): El número de hilos concurrentes utilizados al descargar modelos. Si tienes una buena conexión de red, puedes aumentar esto ligeramente para acelerar las descargas. El valor predeterminado es 10.

  • Otras Opciones (ej., GPU Overhead, Max loaded models, etc.): Estas son opciones de ajuste de rendimiento más avanzadas. Si tienes una GPU compatible (NVIDIA o Apple Silicon), Ollama generalmente la detecta y la usa automáticamente. Max loaded models limita el número de modelos cargados en memoria/VRAM simultáneamente, dependiendo del tamaño de tu RAM/VRAM. Para tareas de traducción por lotes, generalmente solo se carga un modelo a la vez, por lo que el valor predeterminado suele ser suficiente.

  • Orígenes (Origins): Esta es la configuración CORS (Cross-Origin Resource Sharing), que controla qué páginas web (orígenes) pueden acceder a la API de Ollama. El valor predeterminado incluye varias variaciones de http://localhost y http://127.0.0.1, lo cual suele ser suficiente para scripts locales o aplicaciones web locales.

Nota Importante: Si modificas alguna configuración, asegúrate de hacer clic en el botón Save en la esquina inferior derecha de la interfaz para aplicar los cambios. Si encuentras problemas, puedes intentar hacer clic en Reset para restaurar la configuración predeterminada.

Paso 3: Navegar a la Interfaz de Gestión de Modelos

  1. En la barra de navegación izquierda de ServBay, bajo la categoría AI, haz clic en Models (Ollama).

  2. Verás una interfaz de gestión de modelos similar a la segunda captura de pantalla. Aquí se listan los modelos disponibles para descargar y aquellos ya instalados localmente.

Paso 4: Buscar y Descargar un Modelo de Traducción

Ahora necesitamos seleccionar y descargar un LLM adecuado para tareas de traducción. La capacidad de traducción de un LLM a menudo está relacionada con su habilidad general para seguir instrucciones y sus datos de entrenamiento multilingües. Algunas buenas opciones podrían incluir (al momento de escribir esto):

  • Serie Llama 3 (ej., llama3:8b): El último modelo de código abierto de Meta AI, con fuertes capacidades generales y buen seguimiento de instrucciones, generalmente maneja bien las tareas de traducción. La versión 8B tiene requisitos de hardware relativamente moderados.

  • Serie Mistral (ej., mistral:7b): Otro modelo de código abierto de alto rendimiento muy popular conocido por su eficiencia.

  • Serie DeepSeek Coder/LLM (ej., deepseek-llm:7b-chat): Aunque DeepSeek es conocido por sus habilidades de codificación, sus modelos de chat generales generalmente también poseen capacidades de traducción. El deepseek-r1 en la captura de pantalla podría ser una de sus variantes o una versión específica.

  • Modelos de Traducción Especializados (si están disponibles en la biblioteca Ollama): A veces hay modelos optimizados específicamente para la traducción, pero los modelos fuertes de seguimiento de instrucciones generales a menudo también funcionan muy bien.

Realizando la Búsqueda y Descarga:

  1. En el cuadro de búsqueda en la parte superior de la interfaz de gestión de modelos, ingresa el nombre del modelo que deseas encontrar, ej., llama3 o mistral.

  2. La interfaz mostrará dinámicamente una lista de modelos coincidentes, incluyendo diferentes tamaños de parámetros (como 7b, 8b, 70b, etc.) y etiquetas (como latest, instruct, chat).

  3. Consideraciones al seleccionar un modelo:

    • Parámetros (Parameters): Como 7b (7 mil millones), 8b (8 mil millones), 70b (70 mil millones). Cuentas de parámetros más grandes generalmente significan capacidades más fuertes pero también mayores requisitos de memoria (RAM) y memoria de video (VRAM), y una velocidad de inferencia más lenta. Para la traducción por lotes, un modelo 7b u 8b suele ser un buen punto de partida, equilibrando rendimiento y consumo de recursos.

    • Etiquetas (Tags): Los modelos etiquetados como instruct o chat suelen ser mejores para seguir instrucciones (como "Por favor, traduce el siguiente texto a...").

    • Tamaño del Archivo (File Size): Ten en cuenta que los archivos de modelo pueden ser grandes (desde varios GB hasta decenas de GB). Asegúrate de tener suficiente espacio en disco.

  4. Encuentra la versión del modelo que deseas descargar (ej., llama3:8b) y haz clic en el icono de descarga junto a él (generalmente una flecha hacia abajo).

  5. ServBay comenzará a descargar el modelo. Puedes ver el progreso de la descarga. El tiempo de descarga depende de la velocidad de tu red y del tamaño del modelo.

Paso 5: Verificar la Instalación del Modelo

Una vez completada la descarga del modelo, debería aparecer en la lista de modelos instalados en el lado izquierdo de la interfaz Ollama Config. Además, en la interfaz Models (Ollama), el botón de acción para ese modelo podría cambiar a un icono de eliminar (🗑️).

Paso 6: Confirmar que el Servicio Ollama está en Ejecución

Asegúrate de que el indicador de estado en la parte superior de la interfaz Ollama Config muestre verde o un estado de ejecución. ServBay generalmente inicia el servicio Ollama automáticamente cuando inicias la aplicación o habilitas las funciones de IA. Si el servicio no está en ejecución, busca un botón de inicio y actívalo.

En este punto, tu entorno ServBay tiene el servicio Ollama configurado, y has descargado un LLM local listo para la traducción. A continuación, escribiremos el script de Python para llamar a este servicio de IA local.

Parte 3: Escribiendo el Script de Python para Traducción por Lotes

Ahora que tenemos un LLM ejecutándose localmente y accesible a través de una API (http://127.0.0.1:11434), escribamos un script de Python para automatizar el proceso de traducción: iterar a través de todos los archivos Markdown en la carpeta docs especificada, enviar su contenido a Ollama para su traducción y guardar los resultados en nuevos archivos.

Prerrequisitos

  1. Entorno Python: Asegúrate de que Python esté instalado en tu sistema. Puedes verificarlo ejecutando python --version o python3 --version en tu terminal. ServBay viene con Python 3. Si no está instalado, instálalo desde Packages -> Python de ServBay.

Descripción de la imagen

  1. Biblioteca requests: Necesitamos la biblioteca requests para enviar solicitudes HTTP a la API de Ollama. Si aún no está instalada, ejecuta esto en tu terminal:

     pip install requests
 # o
 pip3 install requests

  2. Crear Estructura del Proyecto:

    • Crea una carpeta de proyecto, por ejemplo, servbay_translator.

    • Dentro de la carpeta servbay_translator, crea una subcarpeta llamada docs. Coloca los archivos Markdown (.md) que necesitas traducir en la carpeta docs y sus subcarpetas. Por ejemplo:

        servbay_translator/
  ├── docs/
  │   ├── introduction.md
  │   ├── chapter1/
  │   │   └── setup.md
  │   └── chapter2/
  │       └── usage.md
  └── translate_script.py  (Crearemos este archivo)

    • El script creará automáticamente una carpeta translated_docs para almacenar los archivos traducidos, manteniendo la estructura de directorios original.

Script de Python (translate_script.py)

import os
import requests
import json
import time

# --- Constantes de Configuración ---

# Dirección y puerto de la API de Ollama (consistente con la config de ServBay)
OLLAMA_API_URL = "http://127.0.0.1:11434/api/generate"

# El nombre del modelo que descargaste en ServBay y quieres usar para la traducción
# Asegúrate de que coincida exactamente con el nombre del modelo en Ollama
# Ejemplos: "llama3:8b", "mistral:7b", "deepseek-llm:7b-chat" etc.
MODEL_NAME = "llama3:8b"  # <--- ¡Cambia esto al nombre de tu modelo elegido!

# Directorio que contiene los archivos Markdown fuente
SOURCE_DIR = "docs"

# Directorio para almacenar los archivos traducidos (el script lo creará)
TARGET_DIR = "translated_docs"

# El idioma de destino al que quieres traducir los documentos
TARGET_LANGUAGE = "Spanish" # Ejemplos: "English", "Simplified Chinese", "French", "German", "Japanese"

# Opcional: Añadir un retraso (en segundos) entre solicitudes para evitar sobrecargas o dar tiempo al sistema para responder
REQUEST_DELAY = 1 # Retraso de 1 segundo, ajusta según sea necesario

# --- Función de Llamada a la API de Ollama ---

def translate_text_ollama(text_to_translate, model_name, target_language):
    """
    Traduce el texto dado usando la API de Ollama.

    Args:
        text_to_translate (str): El texto original a traducir.
        model_name (str): El nombre del modelo Ollama a usar.
        target_language (str): El idioma de destino para la traducción.

    Returns:
        str: El texto traducido, o None si ocurrió un error.
    """
    # Construir un prompt de instrucción de traducción claro
    prompt = f"""Translate the following Markdown text into {target_language}.
Preserve the original Markdown formatting (like headings, lists, bold text, code blocks, etc.).
Only output the translated text, without any introductory phrases like "Here is the translation:".

Original Text:
---
{text_to_translate}
---
Translated Text ({target_language}):"""

    headers = {'Content-Type': 'application/json'}
    data = {
        "model": model_name,
        "prompt": prompt,
        "stream": False, # Establecer en False para obtener la respuesta completa de una vez, no en streaming
        # Parámetros opcionales, ajustar según sea necesario, ej., temperature controla la creatividad (más bajo es más conservador)
        # "options": {
        #     "temperature": 0.3
        # }
    }

    try:
        print(f"  Enviando solicitud a Ollama (modelo: {model_name})...")
        # Aumentar el tiempo de espera a 300 segundos para traducciones potencialmente largas
        response = requests.post(OLLAMA_API_URL, headers=headers, json=data, timeout=300)
        response.raise_for_status() # Comprobar errores HTTP (ej., 404, 500)

        response_data = response.json()

        # Extraer el texto traducido de la respuesta
        # La estructura de respuesta /api/generate de Ollama generalmente contiene la salida completa en el campo 'response'
        if 'response' in response_data:
            translated_text = response_data['response'].strip()
            print(f"  Traducción recibida (longitud: {len(translated_text)} caracteres).")
            return translated_text
        else:
            print(f"  Error: Clave 'response' no encontrada en la salida de Ollama: {response_data}")
            return None

    except requests.exceptions.RequestException as e:
        print(f"  Error al llamar a la API de Ollama: {e}")
        return None
    except json.JSONDecodeError:
        print(f"  Error al decodificar la respuesta JSON de Ollama: {response.text}")
        return None
    except Exception as e:
        print(f"  Ocurrió un error inesperado durante la traducción: {e}")
        return None

# --- Lógica Principal de Procesamiento ---

def process_directory(source_base, target_base):
    """
    Recorre recursivamente el directorio fuente, traduce archivos .md,
    y los guarda en el directorio destino, preservando la estructura.
    """
    print(f"\nProcesando directorio: {source_base}")
    for item in os.listdir(source_base):
        source_path = os.path.join(source_base, item)
        target_path = os.path.join(target_base, item)

        if os.path.isdir(source_path):
            # Si es un subdirectorio, procesarlo recursivamente
            print(f"- Subdirectorio encontrado: {item}")
            process_directory(source_path, target_path)
        elif os.path.isfile(source_path) and item.lower().endswith(".md"):
            # Si es un archivo Markdown, traducirlo
            print(f"- Archivo Markdown encontrado: {item}")

            # Asegurar que el directorio padre del archivo destino exista
            target_file_dir = os.path.dirname(target_path)
            if not os.path.exists(target_file_dir):
                print(f"  Creando directorio destino: {target_file_dir}")
                os.makedirs(target_file_dir)

            # Opcional: Comprobar si el archivo destino ya existe y omitir
            # if os.path.exists(target_path):
            #     print(f"  Omitiendo, el archivo destino ya existe: {target_path}")
            #     continue

            try:
                # Leer el contenido del archivo fuente
                print(f"  Leyendo archivo fuente: {source_path}")
                with open(source_path, 'r', encoding='utf-8') as f_in:
                    original_content = f_in.read()

                if not original_content.strip():
                    print("  Omitiendo archivo vacío.")
                    continue

                # Llamar a Ollama para la traducción
                translated_content = translate_text_ollama(original_content, MODEL_NAME, TARGET_LANGUAGE)

                if translated_content:
                    # Escribir el contenido traducido en el archivo destino
                    print(f"  Escribiendo archivo traducido: {target_path}")
                    with open(target_path, 'w', encoding='utf-8') as f_out:
                        f_out.write(translated_content)
                    print("  Traducción completa para este archivo.")
                else:
                    print(f"  Fallo al traducir archivo: {source_path}. Omitiendo.")

                # Añadir retraso entre solicitudes API
                if REQUEST_DELAY > 0:
                    print(f"  Esperando {REQUEST_DELAY} segundo(s)...")
                    time.sleep(REQUEST_DELAY)

            except Exception as e:
                print(f"  Error procesando archivo {source_path}: {e}")
        else:
            print(f"- Omitiendo archivo no Markdown u otro elemento: {item}")

# --- Punto de Entrada del Script ---

if __name__ == "__main__":
    print("Iniciando Proceso de Traducción Masiva de Markdown...")
    print(f"Directorio Fuente: {SOURCE_DIR}")
    print(f"Directorio Destino: {TARGET_DIR}")
    print(f"Idioma Destino: {TARGET_LANGUAGE}")
    print(f"Usando Modelo Ollama: {MODEL_NAME} en {OLLAMA_API_URL}")
    print("-" * 30)

    # Comprobar si el directorio fuente existe
    if not os.path.isdir(SOURCE_DIR):
        print(f"Error: Directorio fuente '{SOURCE_DIR}' no encontrado.")
        print("Por favor, crea el directorio 'docs' y coloca tus archivos Markdown dentro.")
        exit(1)

    # Comprobar/Crear directorio destino
    if not os.path.exists(TARGET_DIR):
        print(f"Creando directorio destino: {TARGET_DIR}")
        os.makedirs(TARGET_DIR)

    # Iniciar procesamiento
    try:
        process_directory(SOURCE_DIR, TARGET_DIR)
        print("\n" + "=" * 30)
        print("¡Proceso de traducción por lotes finalizado!")
        print(f"Los archivos traducidos se guardan en el directorio '{TARGET_DIR}'.")
    except Exception as e:
        print(f"\nOcurrió un error durante el proceso: {e}")

Explicación del Código:

  1. Importar Bibliotecas (import os, requests, json, time):

    • os: Para operaciones de archivos y directorios (recorrer directorios, comprobar rutas, crear directorios, etc.).

    • requests: Para enviar solicitudes HTTP POST a la API de Ollama.

    • json: Para manejar datos JSON en solicitudes/respuestas API (aunque requests maneja gran parte de esto internamente aquí).

    • time: Para añadir retrasos entre solicitudes (time.sleep).

  2. Constantes de Configuración:

    • OLLAMA_API_URL: El endpoint para la API de generación de Ollama. Asegúrate de que coincida con la IP y el puerto en tu configuración de ServBay.

    • MODEL_NAME: ¡Crucial! Debe coincidir exactamente con el nombre (incluyendo la etiqueta) del modelo que descargaste en ServBay y deseas usar. Modifica esto según tu modelo elegido.

    • SOURCE_DIR: El nombre de la carpeta que contiene los archivos .md originales.

    • TARGET_DIR: El nombre de la carpeta donde se guardarán los archivos .md traducidos.

    • TARGET_LANGUAGE: El nombre del idioma al que deseas traducir. Usa nombres de idioma claros como "Simplified Chinese", "French", "German", "English", "Spanish". Los LLMs suelen entender estas instrucciones en lenguaje natural.

    • REQUEST_DELAY: Cuántos segundos esperar después de procesar un archivo antes de comenzar el siguiente. Esto ayuda a prevenir la sobrecarga del servicio Ollama o el agotamiento de los recursos de la máquina local, especialmente al procesar muchos archivos o usar modelos que consumen muchos recursos.

  3. Función translate_text_ollama:

    • Toma el texto original, el nombre del modelo y el idioma de destino como entrada.

    • Construir Prompt: Esto es clave para comunicarse con el LLM. Construimos una instrucción clara diciéndole al modelo:

      • La tarea es "Traducir el siguiente texto Markdown a [Idioma Destino]".

      • Enfatizar "Preservar el formato Markdown original". Esto es vital para la traducción de documentos.

      • Solicitar "Solo mostrar el texto traducido" para evitar frases explicativas adicionales del modelo (como "Aquí está la traducción:").

      • Usar separadores --- para marcar claramente el texto original.

    • Preparar Solicitud API: Establecer las cabeceras de la solicitud (Content-Type: application/json) y el cuerpo de la solicitud (data).

      • model: Especifica el modelo a usar.

      • prompt: Nuestra instrucción cuidadosamente elaborada.

      • stream: False: Queremos el resultado completo de la traducción de una vez, no fragmentos transmitidos.

      • options (parte opcional comentada): Puedes pasar parámetros adicionales de Ollama como temperature (controla la aleatoriedad/creatividad; para la traducción, valores más bajos como 0.2-0.5 suelen ser mejores).

    • Enviar Solicitud: Usar requests.post para enviar la solicitud a la API de Ollama. Se establece un timeout más largo (300 segundos) para manejar archivos potencialmente grandes o respuestas de modelo más lentas.

    • Manejo de Errores:

      • response.raise_for_status(): Comprueba errores a nivel HTTP (como 404 Not Found, 500 Internal Server Error).

      • El bloque try...except captura errores de solicitud de red (requests.exceptions.RequestException), errores de análisis JSON (json.JSONDecodeError), y otros errores inesperados.

    • Analizar Respuesta: Si la solicitud tiene éxito, extrae el campo response de los datos JSON devueltos, que generalmente contiene el texto completo generado por el LLM (es decir, la traducción). .strip() elimina cualquier espacio en blanco al principio/final.

    • Devolver Resultado: Devuelve el texto traducido, o None si ocurrió un error.

  4. Función process_directory:

    • Esta es una función recursiva diseñada para manejar la estructura de directorios.

    • Toma la ruta del directorio fuente actual (source_base) y la ruta del directorio destino correspondiente (target_base).

    • Usa os.listdir para obtener todos los archivos y subdirectorios en el directorio actual.

    • Itera:

      • Si es un subdirectorio: Imprime información y llama recursivamente a process_directory para ese subdirectorio, pasando las rutas fuente y destino actualizadas.

      • Si es un archivo que termina en .md:

        • Imprime información.

        • Crear Directorio Destino: Usa os.path.dirname para obtener el directorio padre esperado del archivo destino. Si este directorio no existe, os.makedirs lo crea (incluyendo cualquier directorio intermedio necesario).

        • Leer Archivo Fuente: Usa with open(...) para leer el contenido del archivo .md usando codificación UTF-8.

        • Omitir Archivos Vacíos: Si el contenido del archivo está vacío, lo omite.

        • Llamar a Función de Traducción: Pasa el contenido del archivo a la función translate_text_ollama para su traducción.

        • Escribir Archivo Destino: Si la traducción tuvo éxito (devolvió algo distinto de None), escribe el resultado traducido en el archivo de la ruta destino correspondiente usando codificación UTF-8.

        • Manejar Fallo: Si la traducción falló, imprime un mensaje de error y omite el archivo.

        • Aplicar Retraso: Llama a time.sleep(REQUEST_DELAY) para esperar el número especificado de segundos.

      • Si no es un archivo .md o directorio: Imprime un mensaje de omisión.

  5. Bloque Principal de Ejecución (if __name__ == "__main__":):

    • Este es el punto de entrada del script.

    • Imprime información de inicio, mostrando los parámetros de configuración.

    • Comprobar Directorio Fuente: Asegura que SOURCE_DIR exista; sale con un error si no.

    • Crear Directorio Destino: Crea TARGET_DIR si no existe.

    • Iniciar Procesamiento: Llama a la función process_directory, comenzando desde el SOURCE_DIR y TARGET_DIR de nivel superior.

    • Finalización y Captura de Errores: Usa un bloque try...except para capturar errores potenciales durante todo el proceso e imprime un mensaje de finalización o información de error al final.

Parte 4: Ejecutando el Script y Consideraciones

Cómo Ejecutar el Script:

  1. Abre la Terminal.

  2. Navega al Directorio del Proyecto: Usa el comando cd para entrar en la carpeta servbay_translator que creaste.

     cd /ruta/a/tu/servbay_translator
 # Ejemplo si usas la ubicación www predeterminada de ServBay:
 # cd /Applications/ServBay/www/servbay_translator

  3. Asegúrate de que ServBay y el Servicio Ollama estén en Ejecución: Vuelve a la interfaz de ServBay y confirma que el servicio AI -> Ollama está activo.

  4. Ejecuta el Script de Python:

     python translate_script.py
 # O usa python3 si 'python' apunta a Python 2 en tu sistema
 # python3 translate_script.py

  5. Observa la Salida: El script comenzará a ejecutarse e imprimirá información de progreso en la terminal, incluyendo qué directorio y archivo está procesando, el estado de las solicitudes enviadas, e información breve sobre los resultados de la traducción o errores.

  6. Comprueba los Resultados: Después de que el script finalice, comprueba la carpeta translated_docs. Deberías ver una estructura de directorios idéntica a la carpeta docs, que contiene los archivos .md traducidos. Abre algunos archivos para comprobar la calidad de la traducción y la preservación del formato Markdown.

Consideraciones y Optimizaciones Potenciales:

  1. Elección del Modelo y Calidad de la Traducción:

    • La calidad de la traducción depende en gran medida del LLM que elijas (MODEL_NAME). Diferentes modelos pueden funcionar de manera diferente en varios pares de idiomas y tipos de texto.

    • Experimenta con diferentes modelos (ej., varias versiones de llama3, mistral, qwen, gemma3, etc.) y tamaños de parámetros para encontrar lo que funciona mejor para tus necesidades.

    • Para pares de idiomas específicos, podría haber modelos especialmente ajustados que funcionen mejor; consulta la comunidad de Ollama o plataformas como Hugging Face.

  2. Ingeniería de Prompts (Prompt Engineering):

    • El prompt en la función translate_text_ollama impacta significativamente el resultado de la traducción. Puedes intentar ajustar las instrucciones, por ejemplo:

      • Especificando explícitamente el idioma fuente (si el LLM lo necesita).

      • Haciendo solicitudes más específicas sobre la preservación del formato.

      • Probando diferentes tonos (formal, informal).

    • Si los resultados de la traducción no son satisfactorios, refinar el prompt suele ser el primer paso.

  3. Preservación del Formato Markdown:

    • Aunque el prompt solicita la preservación del formato, los LLMs a veces pueden omitir o manejar incorrectamente la sintaxis Markdown compleja (como listas anidadas, tablas, identificadores de lenguaje de bloques de código, etc.).

    • Siempre revisa al azar los archivos traducidos, especialmente las secciones con formato complejo. Podría ser necesaria una corrección manual.

  4. Rendimiento y Consumo de Recursos:

    • Ejecutar LLMs es computacionalmente intensivo. La velocidad de traducción depende de tu CPU, memoria (RAM) y si la aceleración por GPU está disponible.

    • Los modelos grandes (ej., 7B+) pueden ser muy lentos sin una GPU. La integración de Ollama en ServBay típicamente utiliza las GPUs disponibles (NVIDIA o Apple Silicon) automáticamente. Puedes verificar las configuraciones relacionadas en la configuración de Ollama de ServBay.

    • Si encuentras cuellos de botella de rendimiento o lag del sistema:

      • Aumenta el valor de REQUEST_DELAY.

      • Intenta usar modelos más pequeños (ej., 3B o 4B) o modelos cuantificados (a menudo indicados por q4, q5, q8, etc., en el nombre del modelo). Los modelos cuantificados sacrifican una pequeña cantidad de precisión por una mayor velocidad y menor uso de recursos. La interfaz de gestión de modelos de ServBay generalmente lista estas versiones cuantificadas.

      • En la configuración de Ollama de ServBay, comprueba si Max loaded models y Parallel Num. están configurados razonablemente (para el procesamiento por lotes de una sola tarea, generalmente no necesitan ser altos).

  5. Manejo de Archivos Grandes:

    • Archivos Markdown muy grandes podrían causar:

      • Tiempos de espera de procesamiento de Ollama (el script establece un tiempo de espera de 300 segundos, que podría necesitar ser más largo).

      • Exceder el límite de la ventana de contexto del modelo, lo que lleva a contenido truncado o traducciones incompletas.

      • Alto consumo de memoria.

    • Para archivos extremadamente grandes, podrías necesitar implementar una estrategia de Fragmentación (Chunking): dividir el archivo grande en fragmentos más pequeños (ej., por párrafo o recuento fijo de caracteres), enviar cada fragmento a Ollama para su traducción por separado, y luego fusionar los resultados. Esto aumenta la complejidad del script.

  6. Manejo de Errores y Reintentos:

    • El script incluye manejo básico de errores pero podría mejorarse. Por ejemplo, implementando un mecanismo de reintento automático: cuando una llamada API falla (debido a problemas de red o a que Ollama no responde temporalmente), esperar un corto período y reintentar automáticamente algunas veces.

    • Registrar errores de forma más detallada para facilitar la solución de problemas.

  7. Traducción Incremental:

    • El script actual procesa todos los archivos cada vez que se ejecuta (a menos que lo canceles manualmente). Podría modificarse para comprobar si el archivo destino existe y si su hora de modificación es más reciente que la del archivo fuente. Si es así, omitirlo, implementando así la traducción incremental (solo traduciendo archivos nuevos o modificados).

  8. Procesamiento Concurrente:

    • Si tu hardware es lo suficientemente potente (especialmente CPU multinúcleo o GPU fuerte) y tu configuración de Ollama permite el procesamiento paralelo (Parallel Num. > 0), considera usar las bibliotecas multiprocessing o threading de Python para procesar múltiples archivos concurrentemente. Esto podría acelerar significativamente el tiempo total de traducción pero aumentará el consumo de recursos y la complejidad del código.

Conclusión: Embárcate en Tu Viaje de IA Local

¡Felicidades! Siguiendo este tutorial, has utilizado con éxito la funcionalidad Ollama integrada de ServBay para configurar un flujo de trabajo de traducción por lotes local, privado y automatizado para documentos Markdown. No solo has aprendido sobre las potentes capacidades de integración de ServBay en el espacio de IA/LLM, sino que también has dominado cómo interactuar con modelos de lenguaje grandes que se ejecutan localmente a través de un simple script de Python para resolver problemas del mundo real.

La ventaja principal de esta solución de IA local radica en mantener tus datos completamente en tus propias manos, eliminando preocupaciones sobre brechas de privacidad o altos costos de API. Al mismo tiempo, te otorga una inmensa flexibilidad y control – puedes elegir libremente modelos, ajustar parámetros, optimizar flujos de trabajo e incluso trabajar sin conexión.

ServBay, como un excelente entorno de desarrollo integrado, demuestra una vez más su naturaleza vanguardista al abrazar Ollama, proporcionando a los desarrolladores y entusiastas de la tecnología una plataforma conveniente para explorar y aplicar tecnologías de IA de vanguardia. La traducción de documentos es solo la punta del iceberg. Basado en este marco, puedes explorar muchas más aplicaciones de la IA local, como:

  • Generación y Explicación de Código: Usando modelos como codellama o deepseek-coder para ayudar con la programación.

  • Resumen de Texto y Extracción de Información: Comprendiendo rápidamente el contenido central de documentos o informes largos.

  • Creación y Pulido de Contenido: Generando publicaciones de blog, borradores de correo electrónico, escritura creativa, etc.

  • Preguntas y Respuestas sobre Base de Conocimiento Local: Combinando técnicas RAG (Retrieval-Augmented Generation) para permitir que los LLMs respondan preguntas basadas en tus documentos locales.

En el futuro, a medida que la tecnología LLM local continúa evolucionando y las características de ServBay iteran, tenemos todas las razones para creer que ejecutar aplicaciones de IA potentes, eficientes y seguras en computadoras personales será cada vez más común. ¡Comienza ahora con este proyecto de traducción por lotes y explora libremente las infinitas posibilidades que ServBay y Ollama traen a tus esfuerzos de IA local!

2
Subscribe to my newsletter

Read articles from Dheeraj Malhotra directly inside your inbox. Subscribe to the newsletter, and don't miss out.

AIservbayllm

Written by

Dheeraj Malhotra
Dheeraj Malhotra