Skip to content

Desarrollo local

Instala y ejecuta Potato en local para desarrollo y pruebas. Cubre la instalación con pip, la configuración, el arranque del servidor y la depuración de problemas comunes al iniciar.

Pon Potato en marcha en tu máquina local para desarrollo y pruebas.

Requisitos previos

  • Python 3.9 o superior
  • Gestor de paquetes pip
  • Git (opcional, para clonar ejemplos)

Instalación

Con pip (recomendado)

bash
pip install potato-annotation

Desde el código fuente

bash
git clone https://github.com/davidjurgens/potato.git
cd potato
pip install -e .

Con dependencias opcionales

bash
# Local speech-to-text and diarization for transcript projects
pip install "potato-annotation[transcribe]"
 
# Hosted model providers for AI support and active learning
pip install "potato-annotation[ai]"
 
# Everything except the multi-gigabyte server-side vision stack
pip install "potato-annotation[all]"

Pon el extra entre comillas para que la shell no interprete los corchetes como un patrón glob. all deja fuera vision a propósito, porque ese grupo instala torch y nada de la experiencia por defecto lo necesita.

Inicio rápido

1. Crear un archivo de configuración

Crea config.yaml:

yaml
annotation_task_name: "My First Annotation Task"
task_dir: "."
port: 8000
 
data_files:
  - data.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral
 
output_annotation_dir: "annotations/"

task_dir es la raíz contra la que se resuelven todas las demás rutas relativas, y Potato se niega a leer fuera de ella. Si la fijas en ., la configuración, el archivo de datos y el directorio de salida quedan en una misma carpeta, y eso es lo que permite mover el proyecto a un servidor más adelante.

2. Preparar datos de ejemplo

Crea data.json:

json
[
  {"id": "1", "text": "I love this product!"},
  {"id": "2", "text": "This is terrible."},
  {"id": "3", "text": "It's okay, nothing special."}
]

3. Iniciar el servidor

bash
potato start config.yaml

4. Acceder a la interfaz

Abre tu navegador en http://localhost:8000

Modo de desarrollo

Modo de depuración

El modo de depuración activa el registro detallado, desactiva el cierre de sesión por inactividad y abre las páginas de administración sin clave para las solicitudes que vienen de tu propia máquina. La página de inicio de sesión se mantiene, y --debug-phase (más abajo) la omite:

bash
potato start config.yaml --debug

No actives nunca el modo de depuración en un servidor desplegado. Un túnel o un proxy inverso en la misma máquina que no añada un encabezado de reenvío hace que todas las solicitudes parezcan locales, y --debug-phase hace que cada visitante inicie sesión como el mismo debug_user. Potato 2.8.2 a 2.11.0 se niegan a arrancar en modo de depuración en la dirección predeterminada 0.0.0.0, así que en esas versiones añade --host 127.0.0.1.

Registro de depuración

Elige qué parte de la aplicación informa:

bash
potato start config.yaml --debug-log server

Los valores aceptados son all, ui, server y none. Usa ui cuando la página de anotación se comporte de forma extraña y server cuando un ítem no se cargue.

Salida detallada

Muestra toda la actividad del servidor:

bash
potato start config.yaml --verbose

Saltar a una fase

Con --debug activado, omite el inicio de sesión y ve directamente a la fase en la que estás trabajando en lugar de pasar por el consentimiento y las instrucciones en cada reinicio:

bash
potato start config.yaml --debug --debug-phase annotation

Estructura de directorios

Organización recomendada del proyecto:

text
my-annotation-project/
├── config.yaml           # Main configuration, inside task_dir
├── data/
│   ├── training.json     # Practice items for the training phase
│   └── main.json         # Annotation data
├── annotations/          # output_annotation_dir
├── media/                # media_directory, served at /media/
└── templates/            # site_dir, if you override the default templates

Solo config.yaml y el archivo de datos son obligatorios. Potato incluye sus propias plantillas, así que define site_dir y añade una carpeta templates/ solo cuando vayas a reemplazarlas, y apunta site_file a un archivo concreto para renderizar con él la página de anotación.

Probar tu configuración

Validar la configuración

Comprueba la configuración igual que la comprueba el servidor al arrancar, antes de gastar un arranque en ella:

bash
potato validate config.yaml

Añade --strict para que las advertencias, como una clave no reconocida, hagan fallar la ejecución en lugar de imprimirse y dejarla pasar.

Modo de vista previa

Muestra lo que declara una configuración y renderízala en un navegador sin iniciar un servidor completo:

bash
potato preview config.yaml

Las capturas de pantalla necesitan el extra del navegador sin interfaz, pip install "potato-annotation[preview]":

bash
potato preview config.yaml --screenshot preview.png

Problemas comunes

Puerto ya en uso

bash
# Use a different port
potato start config.yaml -p 8080

O defínelo en config.yaml, y la opción -p lo sobrescribe:

yaml
port: 8080

Archivo de datos no encontrado

Asegúrate de que las rutas sean relativas a la ubicación del archivo de configuración:

yaml
# If data is in a subdirectory
data_files:
  - data/main.json

Las rutas se resuelven contra task_dir, y Potato se niega a cargar un archivo fuera de él, así que mueve los datos dentro del directorio de la tarea en lugar de apuntar a una ruta absoluta en otro lugar de la máquina.

Permiso denegado

Comprueba los permisos de los archivos:

bash
chmod 755 annotations/
chmod 644 data/*.json

Varios usuarios en local

Para probar escenarios con varios usuarios:

yaml
user_config:
  allow_all_users: true
 
login:
  type: url_direct
  url_argument: user_id

url_direct lee el nombre de usuario directamente de la URL y no pide contraseña, así que puedes abrir dos perfiles del navegador y anotar como dos personas sin registrar cuentas:

  • http://localhost:8000/?user_id=annotator1
  • http://localhost:8000/?user_id=annotator2

Restablecer las anotaciones

Potato escribe un directorio por anotador dentro de output_annotation_dir, y cada uno contiene el user_state.json de esa persona:

bash
# Remove one annotator's work
rm -rf annotations/annotator1
 
# Or clear every annotator
rm -rf annotations/*
 
# Restart server
potato start config.yaml

Eliminar el directorio de un usuario elimina sus asignaciones junto con sus respuestas, así que una nueva ejecución vuelve a asignar los ítems desde cero.

Variables de entorno

Configuración mediante el entorno:

bash
# Keeps sessions valid across restarts; required for OAuth
export POTATO_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
 
# Fixes the shared admin key instead of letting Potato generate one per task
export POTATO_ADMIN_API_KEY="your-admin-key"
 
potato start config.yaml

Sin POTATO_SECRET_KEY, Potato genera una clave de firma aleatoria en cada arranque, lo que cierra la sesión de todo el mundo en cada reinicio.

Uso con entornos virtuales

venv

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

Conda

bash
conda create -n potato python=3.10
conda activate potato
pip install potato-annotation

Integración con IDE

VS Code

Instala la extensión YAML para tener soporte de archivos de configuración:

json
// settings.json
{
  "yaml.schemas": {
    "https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json": "config.yaml"
  }
}

Las configuraciones descargadas del Diseñador de estudios ya llevan ese esquema en una línea # yaml-language-server:, así que se validan en el editor sin este ajuste.

PyCharm

Crea una configuración de ejecución:

  1. Add → Python
  2. Script: potato
  3. Parámetros: start config.yaml
  4. Directorio de trabajo: la ruta de tu proyecto

Próximos pasos