Pon tu estudio de Potato en línea

Para poner un estudio de Potato en línea, ejecutas tu tarea en un ordenador al que tus anotadores puedan llegar mediante una dirección web, proteges las anotaciones mientras dura el estudio y descargas las anotaciones al final. Pedirlo al equipo de TI de tu institución y pulsar un botón de despliegue que preparó un colega son las dos vías que no necesitan una terminal por tu parte.

Desplegar un estudio significa trasladar la tarea de Potato que construiste desde tu propio ordenador a un servidor, un ordenador que permanece encendido y conectado a internet. Los anotadores abren entonces la tarea en un navegador web desde cualquier lugar, y Potato guarda cada respuesta en el servidor mientras trabajan. La vista previa del Study Designer ejecuta Potato dentro de tu propio navegador, y nadie más puede acceder a esa copia. Un estudio creado en el Designer sigue necesitando una de las vías siguientes.

Todas las vías parten de la misma carpeta de proyecto. En el Study Designer, el botón Download project (.zip) guarda config.yaml (el archivo que describe tu tarea), un archivo de datos de muestra y un README. El archivo de muestra contiene tres ítems de marcador de posición. Sustituye el archivo de muestra por tus propios ítems antes de desplegar, en el formato que describe Formatos de datos.

Elegir una vía

Las vías se diferencian en quién hace el trabajo técnico, cuánto cuesta el servidor y cuánto tiempo puede seguir activo el estudio. Los costes de abajo proceden de las listas de precios de los hosts y de las estimaciones del propio Potato a 2026-11-04, y las esperas son orientaciones aproximadas, no mediciones:

Si tienes dudas, empieza por tu equipo de TI. Un servidor dentro de tu institución mantiene los datos en equipos que tu institución ya gestiona, y el equipo de TI puede encargarse de las actualizaciones de seguridad y de las copias de seguridad.

Pedir ayuda al equipo de TI o de computación científica

Muchas universidades y hospitales tienen un servicio de computación para la investigación que aloja aplicaciones web para estudios. Para un equipo así, Potato es una aplicación web corriente, y el equipo puede partir de un resumen de una página con lo que Potato necesita.

1. Descarga el proyecto desde el Study Designer y sustituye el archivo de datos de muestra por tus ítems.
2. Envía a tu equipo de TI la carpeta del proyecto y un enlace a Requisitos de servidor de Potato para tu equipo de TI.
3. Cuéntale al equipo quiénes son tus anotadores, cuántos participarán y cuánto dura el estudio.
4. Indica cómo deben iniciar sesión los anotadores. Los colegas con cuentas institucionales pueden usar el inicio de sesión único, el acceso que tu institución ya gestiona, y los anotadores externos pueden usar los nombres de usuario que tú listes.
5. Indica si los ítems o las respuestas contienen información personal o sensible, y nombra la aprobación ética bajo la que se realiza el estudio.
6. Pide al equipo la dirección web del estudio, la clave de administración que abre el panel de administración de Potato y un plan para las copias de seguridad y para entregarte los datos cuando termine el estudio.

Cuando llegue la dirección, repasa Antes de invitar a los anotadores antes de enviar la dirección a nadie.

Pulsar un botón de despliegue que preparó un colega

Un botón de despliegue es un enlace en la página de un repositorio de código que configura una copia de una tarea de Potato en los servidores de una empresa de alojamiento, solo con formularios en tu navegador. Un colega que use git y una terminal crea el botón una vez, desde un repositorio que contiene tu carpeta de proyecto, con el comando potato deploy button. Ejecutar Potato en local o en la nube es la página que debes enviar a ese colega.

El botón funciona con tres hosts, que cobran de forma distinta:

• Render ejecuta el estudio en un plan gratuito sin método de pago. Un servicio gratuito de Render se suspende tras 15 minutos sin visitantes y tarda aproximadamente un minuto en despertar cuando llega el siguiente anotador.
• Heroku cobra $7 al mes por el servidor que crea el botón. Heroku exige una cuenta verificada, normalmente con una tarjeta de crédito, antes de que puedas crear una aplicación.
• AWS ejecuta un servidor Lightsail por $12 al mes. El botón de AWS lee la tarea de un repositorio público, así que solo conviene a ítems que puedan ser públicos.

Render y Heroku borran el disco del servidor cada vez que el servidor se reinicia. Por eso el botón copia las anotaciones cada cinco minutos a un conjunto de datos privado en Hugging Face, un sitio para compartir datos y modelos, y vuelve a copiar las anotaciones cada vez que el servidor arranca. Tú nombras ese conjunto de datos al pulsar, y el conjunto de datos pertenece a tu cuenta.

Antes de pulsar, reúne tres cosas:

• una cuenta en el host, Render o Heroku;
• una cuenta gratuita de Hugging Face, con un token de acceso con permiso de escritura, creado en huggingface.co/settings/tokens; y
• acceso al repositorio, si el repositorio es privado. Heroku te pide vincular tu cuenta de GitHub para un repositorio privado.

Después, despliega:

1. Pulsa el botón del README del repositorio e inicia sesión en el host.
2. Dale un nombre a la aplicación. El nombre pasa a formar parte de la dirección web del estudio.
3. En POTATO_BACKUP_HF_REPO, escribe un nombre de conjunto de datos formado por tu nombre de usuario de Hugging Face y un nombre para el estudio, como your-username/my-study-annotations. Cuando el nombre es nuevo, Potato crea el conjunto de datos y lo hace privado.
4. Pega tu token de Hugging Face en HF_TOKEN. Deja todos los demás campos con el valor que rellenó el botón.
5. Inicia el despliegue y espera a que el host informe de que la aplicación está en marcha. Abre la dirección web que muestra el host.
6. Busca la clave de administración, una contraseña que el host generó durante el despliegue. En Heroku, la clave es la entrada POTATO_ADMIN_API_KEY de la pestaña Settings de la aplicación, y en Render la misma entrada está en la página Environment del servicio.
7. Abre la dirección del estudio con /admin añadido al final, y pega la clave de administración para abrir el panel de administración.

El repositorio fija la tarea, los ítems y la lista de anotadores. Termina la tarea antes de pulsar, porque cualquier cambio posterior pasa por el colega que creó el botón. Mantén el repositorio privado, salvo que los ítems puedan ser públicos.

Compartir un enlace desde tu propio ordenador

Tu propio ordenador puede servir un piloto durante una tarde. Los anotadores abren un enlace web temporal, las anotaciones llegan a la carpeta de tu proyecto y el enlace deja de funcionar cuando cierras el comando. La vía necesita una terminal, un programa para escribir comandos, que es Terminal en un Mac (en Aplicaciones y después Utilidades) y PowerShell en Windows (busca «PowerShell» en el menú Inicio).

1. Instala Python 3.9 o posterior desde python.org/downloads. En Windows, la descarga es el gestor de instalación de Python. En un Mac, la descarga es el instalador de macOS.

2. Abre la terminal e instala Potato. En un Mac, escribe:

   bashCopiar

   python3 -m pip install potato-annotation

   En Windows, escribe:

   powershellCopiar

   py -m pip install potato-annotation

3. Descomprime el proyecto que descargaste del Study Designer. En un Mac, haz doble clic en el archivo .zip. En Windows, haz clic derecho en el archivo y elige Extract All. Sustituye el archivo de datos de muestra por tus ítems.

4. Mueve la terminal a la carpeta del proyecto e inicia Potato. El nombre de carpeta de abajo es un ejemplo, así que usa el nombre de tu propia carpeta. En un Mac:

   bashCopiar

   cd ~/Downloads/my-task
   python3 -m potato start config.yaml

   En Windows:

   powershellCopiar

   cd $HOME\Downloads\my-task
   py -m potato start config.yaml

5. Abre http://localhost:8000 en tu navegador. Solo tu ordenador puede acceder a esa dirección. Pulsa Ctrl-C en la terminal para detener Potato.

6. Para dejar entrar a otras personas, instala cloudflared, un programa gratuito de Cloudflare que no necesita cuenta. En un Mac con Homebrew, ejecuta brew install cloudflared. En Windows, descarga el instalador de Windows desde la página de descargas de Cloudflare.

7. Ejecuta potato share en lugar de potato start:

   bashCopiar

   python3 -m potato share config.yaml

   En Windows, escribe py -m potato share config.yaml. Potato muestra quién podrá iniciar sesión y pregunta antes de publicar nada. Escribe y, y Potato muestra un enlace https:// para enviar a tus anotadores.

El enlace funciona solo mientras el comando está en marcha. Cerrar la terminal, poner el ordenador en reposo o cambiar de red termina el enlace, y una nueva ejecución muestra un enlace nuevo. Algunas redes universitarias bloquean los enlaces trycloudflare.com que crea cloudflared. Si un anotador informa de un enlace bloqueado, potato share config.yaml --backend tailscale usa Tailscale en su lugar. Tailscale necesita una cuenta gratuita. Si potato share informa No tunnel backend found, Potato no encontró cloudflared en tu ordenador, y el mensaje lista los comandos de instalación.

Instalación cubre los entornos virtuales y las funciones opcionales, y Ejecutar Potato en local o en la nube cubre potato share con más detalle.

Alquilar un servidor con un comando

potato deploy up alquila un servidor a una empresa de nube, obtiene un certificado HTTPS (el candado de la barra de direcciones del navegador), sube la carpeta de tu proyecto, inicia el estudio y muestra la dirección web. El comando necesita la configuración de la terminal de los pasos 1 a 3 de arriba, una cuenta en la empresa de nube y un token de API, una clave parecida a una contraseña que permite que un programa actúe en tu cuenta. La guía de cada host cubre la cuenta y el token desde el principio:

Todos los hosts usan los mismos dos comandos, y la guía de cada host da el nombre del proveedor y el comando de instalación del host. El primer comando muestra el plan y el coste mensual y no crea nada, y el segundo crea el servidor después de que confirmes:

potato deploy up config.yaml --provider aws --dry-run
potato deploy up config.yaml --provider aws

El botón Duplicate this Space del propio Hugging Face copia un Space en el navegador, pero una copia de un Space de Potato conserva los ajustes de copia de seguridad del propietario original y pierde los secretos del original. Despliega un Space de Potato con potato deploy up --provider huggingface en su lugar.

Antes de invitar a los anotadores

Repasa esta lista una vez que el estudio tenga una dirección web, sea cual sea la vía que seguiste:

• Decide quién puede iniciar sesión. La configuración cerrada más sencilla es una lista de nombres de usuario. En el Study Designer, desactiva Allow All Users y añade a cada anotador en Authorized Users. Cada anotador de la lista elige una contraseña al registrarse en la primera visita, y Potato rechaza a quien no esté en la lista. Envía a cada anotador su nombre de usuario directamente, porque la primera persona que registra un nombre de usuario de la lista se queda con esa cuenta. Para las cuentas institucionales, consulta Autenticación SSO y OAuth, y para los trabajadores de crowdsourcing, consulta Integración de crowdsourcing. Con Allow All Users activado, cualquiera que encuentre la dirección puede crear una cuenta. Conserva esa opción para las demostraciones públicas.
• Conoce dónde están las anotaciones. Potato guarda las respuestas de cada anotador mientras trabaja, en un archivo llamado user_state.json dentro de una carpeta por anotador. Las carpetas están en la carpeta de salida que nombra la configuración, a la que el Study Designer llama output. En tu propio ordenador, esa carpeta está dentro de la carpeta de tu proyecto. En un despliegue con botón, el conjunto de datos de Hugging Face contiene la copia que sobrevive a un reinicio. En un servidor alquilado, potato deploy pull descarga la carpeta. En un servidor institucional, pregunta a TI cómo se hace la copia de seguridad del servidor.
• Prueba con un segundo navegador. Abre la dirección del estudio en una ventana privada, que es Incógnito en Chrome, Ventana privada en Safari y Firefox, y InPrivate en Edge. Añade a la lista un nombre de usuario como pilot-test, regístrate con ese nombre y responde tres ítems. Cierra la ventana, vuelve a iniciar sesión y comprueba que las respuestas siguen allí. Después abre el panel de administración y comprueba que aparece el anotador de prueba. Prueba la dirección en un teléfono si los anotadores pueden trabajar desde teléfonos.
• Mantén privada la clave de administración. La clave de administración abre el panel de administración en /admin. El panel muestra las respuestas de todos los anotadores. En tu propio ordenador, Potato guarda la clave en admin_api_key.txt, en la carpeta del proyecto, la primera vez que abres /admin.
• Escribe la invitación. Envía a cada anotador la dirección, el nombre de usuario, cuánto tarda la tarea y a quién contactar cuando algo salga mal.

Obtener los resultados

El panel de administración descarga los resultados a tu ordenador sin terminal. Abre /admin, introduce la clave de administración y elige Publish Dataset. En Target, elige Local archive, define Data format como CSV para una hoja de cálculo y pulsa Publish. Cuando el archivo esté listo, pulsa Download archive.

El archivo contiene las respuestas de cada anotador, los ítems y las etiquetas combinadas por mayoría de votos. Un README del archivo informa de los recuentos de etiquetas y del acuerdo entre anotadores. Los nombres de los anotadores se sustituyen por A1, A2 y así sucesivamente, salvo que desmarques Anonymize annotators. Las respuestas de las encuestas quedan fuera del archivo salvo que marques Include survey / phase responses, porque las respuestas de las encuestas pueden contener información personal.

Desde una terminal, python -m potato.export escribe las mismas anotaciones en una carpeta, en cualquiera de los formatos de exportación de Potato:

python -m potato.export --config config.yaml --format csv --output results

En un servidor creado con potato deploy up, potato deploy pull config.yaml descarga todo lo que recogió el servidor, bases de datos incluidas.

Cerrar el estudio para que el servidor deje de costar dinero

Descarga los resultados antes de eliminar nada, y abre la descarga para comprobar que están las respuestas del último anotador. Después apaga el servidor del modo que exige la vía:

• Tu propio ordenador. Pulsa Ctrl-C en la terminal. No se cobró nada.
• Tu equipo de TI. Avisa al equipo de que el estudio terminó, pide una copia de la carpeta de salida y pregunta cuánto tiempo se conservará la copia del servidor.
• Un botón de despliegue. Elimina la aplicación desde la pestaña Settings de la aplicación en Heroku, o elimina el servicio desde su página Settings en Render. El conjunto de datos de Hugging Face contiene una copia completa de las anotaciones. Cuando ya no necesites la copia de seguridad, elimina el conjunto de datos desde su página de ajustes.
• Un servidor alquilado. Ejecuta potato deploy pull config.yaml, comprueba la carpeta descargada y después ejecuta potato deploy destroy config.yaml. Potato se niega a destruir un servidor cuyos datos nunca se han descargado.

Preguntas frecuentes

¿Cómo creo un servidor de Potato para mi estudio?

Creas un servidor de Potato ejecutando tu tarea en un ordenador al que tus anotadores puedan llegar mediante una dirección web. El equipo de TI de tu institución puede ejecutar la tarea por ti, un colega puede preparar un botón de despliegue que tú pulses, potato share puede servir un piloto desde tu portátil y potato deploy up puede alquilar un servidor por ti. La tabla de Elegir una vía compara las vías por coste y por el trabajo de terminal que exige cada una.

¿Cómo instalo Potato en mi PC?

Instala Python 3.9 o posterior desde python.org, y después escribe py -m pip install potato-annotation en PowerShell en Windows, o python3 -m pip install potato-annotation en Terminal en un Mac. Tras la instalación, py -m potato start config.yaml en Windows o python3 -m potato start config.yaml en un Mac inicia una tarea. Instalación cubre las funciones opcionales.

Palabras que usa esta página

• Servidor. Un servidor es un ordenador que permanece encendido y conectado a internet para que otras personas puedan usar un programa del ordenador mediante un navegador web.
• URL, o dirección web. Una URL es la dirección que los anotadores escriben o en la que hacen clic, como https://my-study.example.edu. Un dominio es la parte del nombre de la dirección, aquí my-study.example.edu.
• HTTPS. HTTPS cifra todo lo que va entre el navegador del anotador y el servidor, incluidas las contraseñas y las respuestas. Los navegadores muestran un candado para una dirección HTTPS.
• Puerto. Un puerto es un punto de entrada numerado de un ordenador. Potato escucha en el puerto 8000 salvo que la configuración nombre otro puerto, y la dirección local http://localhost:8000 termina con ese número.
• Terminal. Una terminal es un programa para escribir comandos, llamado Terminal en un Mac y PowerShell en Windows.
• Clave de administración. La clave de administración es una contraseña larga que abre el panel de administración de Potato.
• Token de API. Un token de API es una clave parecida a una contraseña que permite que un programa, como el comando de despliegue de Potato, actúe en tu cuenta en una empresa de alojamiento.

Más información

• Requisitos de servidor de Potato para tu equipo de TI, la página que debes enviar a tu equipo de TI
• Ejecutar Potato en local o en la nube, para todos los hosts, los botones de despliegue y las copias de seguridad
• Desplegar un servidor de anotación, para elegir un host para un estudio largo
• Ejecutar Potato en Docker, para servidores que ejecutan contenedores
• Panel de administración, para seguir el progreso mientras el estudio está en marcha