Skip to content

Inicio Rápido

Pon en marcha Potato en menos de 5 minutos. Instálalo con pip, escribe una configuración YAML, inicia el servidor y anota tu primer conjunto de datos sin escribir código.

Esta guía te lleva de una instalación nueva a anotar datos en menos de 5 minutos. Muestra cómo escribir una tarea por tu cuenta. La otra forma de empezar es describir el estudio a un agente de programación y dejar que potato-skill lo diseñe y lo construya, algo que cubre Inicio rápido con un agente de programación.

Potato en cinco pasos: instalar, configurar, iniciar el servidor, anotar en el navegador y exportarPotato en cinco pasos

Requisitos Previos

  • Python 3.9 o superior
  • Gestor de paquetes pip
  • Una terminal

Instalación

Recomendamos instalar Potato en un entorno virtual para que no choque con el Python del sistema:

bash
python -m venv potato-env
source potato-env/bin/activate   # Windows: potato-env\Scripts\activate
pip install potato-annotation

Comprueba la instalación:

bash
python -c "import potato; print(potato.__version__)"

Deberías ver 2.12.1 en la salida. Desde la versión 2.9, potato --version muestra el mismo número y añade el commit cuando lo ejecutas desde una copia del repositorio.

Crea Tu Primer Proyecto

1. Crea un directorio de proyecto

bash
mkdir my-annotation-task
cd my-annotation-task

2. Crea tu archivo de datos

Crea una carpeta data y, dentro de ella, un archivo llamado data.json:

bash
mkdir data
json
[
  {"id": "1", "text": "I love this product! It's amazing."},
  {"id": "2", "text": "This is the worst experience ever."},
  {"id": "3", "text": "It's okay, nothing special."}
]

Potato también acepta .jsonl (un objeto JSON por línea), .csv y .tsv en data_files. Apunta a un archivo con la extensión correspondiente y Potato elige el lector a partir de ella.

3. Crea tu configuración

Crea un archivo llamado config.yaml en tu directorio de proyecto:

Aislamiento de rutas: Las rutas relativas de tu configuración (como data_files o output_annotation_dir) se resuelven respecto a task_dir y deben quedarse dentro de él. Las rutas que se resuelven fuera de task_dir se rechazan para evitar ataques de path traversal.

yaml
annotation_task_name: "Sentiment Analysis"
 
# All relative paths below are resolved against task_dir.
task_dir: "."
 
# Data configuration
data_files:
  - "data/data.json"
 
# Tell Potato which fields in each record to use.
# id_key = unique identifier; text_key = the text shown to annotators.
item_properties:
  id_key: id
  text_key: text
 
# Where per-user annotation state is stored (relative to task_dir).
output_annotation_dir: "annotation_output/"
 
# Also write a periodic flat export, because the per-user state files are
# awkward to analyze. No exporter is named "json", so use "jsonl".
export_annotation_format: "jsonl"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"   # required for radio schemes
    labels:
      - Positive
      - Negative
      - Neutral
 
# Skip password authentication so anyone can log in with just a username.
require_password: false

Consejo: Puedes validar tu configuración sin lanzar el servidor completo con la CLI de Vista Previa. Es la forma más rápida de detectar erratas antes de empezar a anotar.

4. Inicia el servidor

bash
potato start config.yaml -p 8000

La forma larga equivalente:

bash
python -m potato start config.yaml -p 8000

Si el puerto 8000 ya está en uso, elige otro con -p 8001. Para detener el servidor, pulsa Ctrl+C en la terminal.

Primera ejecución más rápida: Añade --debug --debug-phase=annotation para saltarte las páginas de inicio de sesión y de consentimiento mientras experimentas, con potato start config.yaml --debug --debug-phase=annotation. A partir de ahí, cada visitante inicia sesión como un único debug_user compartido, así que úsalo solo en tu propia máquina.

5. Abre tu navegador

Navega a http://localhost:8000. Verás una pantalla de inicio de sesión con un único campo de nombre de usuario. Escribe cualquier cosa (por ejemplo alice), haz clic en Continue y ya estás anotando.

Cada vez que seleccionas una etiqueta y haces clic en Next, tu anotación se guarda automáticamente. No hay un botón de "guardar" aparte.

Dónde Se Guardan Tus Anotaciones

Potato escribe el estado de cada usuario mientras anotas:

text
my-annotation-task/
├── config.yaml
├── data/
│   └── data.json
└── annotation_output/              # created automatically
    └── alice/
        └── user_state.json         # one folder per username

user_state.json contiene el estado completo de las anotaciones de ese usuario. Para generar un archivo plano y consolidado con todos los anotadores, ejecuta la CLI de exportación de Potato, que describe la documentación de exportación. Ejecuta python -m potato.export --list-formats para ver todos los formatos que registra.

Problemas Comunes en la Primera Ejecución

  • Address already in use. El puerto 8000 está ocupado. Usa -p 8001 (o cualquier puerto libre).
  • KeyError: 'description'. A un esquema radio (o similar) le falta su campo obligatorio description. Todos los esquemas necesitan uno.
  • Path ... is outside the task directory. Una ruta de data_files o de output_annotation_dir sale de task_dir. Mantén todo dentro de la carpeta del proyecto, o define task_dir como una ruta absoluta que lo contenga.
  • La página de inicio de sesión muestra un campo de contraseña. Olvidaste require_password: false, o estás en una pestaña del navegador con caché. Reinicia el servidor y fuerza la recarga de la página.

Preguntas frecuentes

Las preguntas siguientes tratan la instalación de Potato, su ejecución en Docker y la comprobación de una configuración antes de que la vean los anotadores.

¿Cómo se instala Potato?

Instálalo desde PyPI con pip install potato-annotation, en Python 3.9 o superior. Instalarlo en un entorno virtual mantiene las dependencias de Potato separadas del Python del sistema, y potato --version confirma la instalación mostrando el número de versión.

¿Se puede ejecutar Potato en Docker?

Sí. Potato publica una imagen precompilada, ghcr.io/davidjurgens/potato, en GitHub Container Registry. La carpeta de tu proyecto se monta en el contenedor en /app y el servidor escucha en el puerto 7860 dentro de él, así que una sola imagen sirve para cualquier tarea. Define POTATO_SECRET_KEY para que las sesiones de los anotadores sobrevivan a un reinicio. Despliegue de Potato en un Servidor incluye el comando docker run completo.

¿Cómo compruebo una configuración de Potato antes de que la vean los anotadores?

Ejecuta potato validate config.yaml --strict, que comprueba la configuración igual que lo hace el servidor al arrancar y convierte las advertencias, como una clave no reconocida, en fallos. Después, potato preview config.yaml muestra lo que declara la configuración y renderiza la interfaz en un navegador, así que ves la tarea tal como la verá un anotador antes de que nadie inicie sesión.

Próximos Pasos

Herramientas y Utilidades

Cuando te sientas cómodo con lo básico, consulta estas herramientas útiles: