Skip to content

本地开发

在本地安装并运行 Potato，用于开发和测试。内容涵盖 pip 安装、配置文件、启动服务器，以及排查常见的启动问题。

让 Potato 在你自己的机器上跑起来，用于开发和测试。

前置条件

  • Python 3.9 或更高版本
  • pip 包管理器
  • Git（可选，用于克隆示例）

安装

使用 pip（推荐）

bash
pip install potato-annotation

从源码安装

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

带可选依赖安装

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]"

给额外依赖名加引号，这样 shell 不会把方括号当成通配符。all 特意不包含 vision，因为那一组会装上 torch，而默认体验里没有任何功能用得到它。

快速开始

1. 创建配置文件

创建 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 是其他所有相对路径的解析根目录，Potato 不会读取它之外的内容。把它设成 .，配置文件、数据文件和输出目录就都在同一个文件夹里，项目之后才能整体搬到服务器上。

2. 准备示例数据

创建 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. 启动服务器

bash
potato start config.yaml

4. 打开界面

在浏览器中访问 http://localhost:8000

开发模式

调试模式

调试模式会打开详细日志，关掉会话空闲超时，并让来自你自己机器的请求不用密钥就能打开管理页面。登录页面仍然保留，--debug-phase（见下文）会跳过它：

bash
potato start config.yaml --debug

已经部署的服务器上绝不能打开调试模式。同一台机器上不添加转发请求头的隧道或反向代理会让每个调用方看起来都来自本机，而 --debug-phase 会让每个访问者都以同一个 debug_user 身份登录。Potato 2.8.2 到 2.11.0 在默认的 0.0.0.0 地址上拒绝以调试模式启动，所以在这些版本上要加上 --host 127.0.0.1。

调试日志

选择由应用的哪一侧输出日志：

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

可取的值是 all、ui、server 和 none。标注页面表现异常时用 ui，某个条目加载不出来时用 server。

详细输出

查看服务器的全部活动：

bash
potato start config.yaml --verbose

直接跳到某个阶段

打开 --debug 后，可以跳过登录，直接跳到你正在调整的阶段，不必每次重启都点过知情同意和说明页：

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

目录结构

推荐的项目布局：

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

必需的只有 config.yaml 和数据文件。Potato 自带模板，所以只有在要替换模板时才需要设置 site_dir 并加一个 templates/ 文件夹，再用 site_file 指向渲染标注页面所用的那个文件。

测试配置

校验配置

用服务器启动时所用的同一套检查来查配置，省得为此白启动一次：

bash
potato validate config.yaml

加上 --strict，警告（比如出现无法识别的键）就会让这次运行失败，而不是打印出来后照样通过。

预览模式

查看一份配置声明了什么，并在浏览器里渲染出来，不用启动完整服务器：

bash
potato preview config.yaml

截图需要无头浏览器那组额外依赖，pip install "potato-annotation[preview]"：

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

常见问题

端口已被占用

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

也可以写在 config.yaml 里，-p 参数会覆盖它：

yaml
port: 8080

找不到数据文件

确认路径是相对于配置文件所在位置的：

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

路径相对 task_dir 解析，Potato 不会加载它之外的文件，所以要把数据挪到任务目录下，而不是指向机器上别处的绝对路径。

权限被拒绝

检查文件权限：

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

在本地模拟多个用户

用于测试多用户场景：

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

url_direct 直接从 URL 里读用户名，不要求密码，于是你可以开两个浏览器配置，不注册账号就以两个人的身份标注：

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

重置标注

Potato 在 output_annotation_dir 下给每个标注者写一个目录，里面放着这个人的 user_state.json：

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

删掉某个用户的目录，会连同答案一起删掉分配给他的任务，所以重新运行时条目会从头分配。

环境变量

通过环境变量配置：

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

没有 POTATO_SECRET_KEY，Potato 每次启动都会生成一个随机签名密钥，每次重启都会把所有人登出。

配合虚拟环境使用

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

IDE 集成

VS Code

安装 YAML 扩展以获得配置文件支持：

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

从研究设计器下载的配置已经在 # yaml-language-server: 那一行带上了这个 schema，不做这项设置也能在编辑器里校验。

PyCharm

建立一个运行配置：

  1. 添加 → Python
  2. 脚本：potato
  3. 参数：start config.yaml
  4. 工作目录：你的项目路径

下一步