주석 서버 배포하기
연구 기간, 비용을 내는 사람, 갖고 있는 서버를 기준으로 주석 연구의 호스트를 고르고, potato deploy로 HTTPS, 백업, 데이터 회수를 처리합니다.
실제 연구에 쓰는 주석 서버에는 공개 HTTPS 주소, 내 주석자만 들여보내는 로그인, 재시작해도 남는 저장소, 그리고 연구가 끝났을 때 주석을 돌려받을 방법이 필요합니다. Potato에서는 potato deploy up이 파일럿에서 쓴 설정으로 호스트와 인증서를 만들고, 디스크가 지워지는 호스트에는 백업을 설정하며, 링크를 가진 누구나 로그인할 수 있는 상태라면 배포하기 전에 경고합니다.
여기서 주석 서버란 주석자가 브라우저로 여는 웹 애플리케이션을 말합니다. 연구가 이어지는 몇 주 동안 주석자가 접속할 수 있도록 노트북이 아닌 다른 곳에서 실행합니다. 파일럿을 마친 작업을 그곳으로 옮기면 주소, 로그인, 데이터를 저장하는 곳, 그리고 컴퓨터를 관리해야 하는 사람이 바뀝니다.
연구용 서버의 네 가지 요건
아래 요건은 각각 주석자나 데이터 중 하나를 보호합니다.
- 공개 HTTPS 주소. 주석자는 작업에 비밀번호와 레이블을 입력하므로, 연결은 HTTPS로 암호화해야 합니다. Let's Encrypt 인증서는 무료이며, 이를 받으려면 서버에 공개 주소가 있어야 합니다.
- 내 주석자만 들여보내는 로그인. 공개 주소는 누군가 찾아낼 수 있고, 공개 가입을 허용한 작업은 주소를 찾은 사람을 누구든 받아들입니다. 이름이 정해진 계정의 명단(비밀번호 관리), Google, GitHub, 소속 기관을 통한 로그인(SSO 및 OAuth 인증), 또는 크라우드소싱 연구라면 플랫폼이 워커에게 나눠 주는 링크(크라우드소싱 연동)를 사용하십시오.
- 재시작해도 남는 저장소. 어떤 호스트는 서버가 재시작될 때마다 디스크를 지웁니다. 그런 호스트에서 하는 연구에는 자동으로 복원되는 백업이 필요하며, 그렇지 않으면 다시 들어온 주석자는 빈 작업을 보게 됩니다.
- 데이터를 돌려받을 방법. Potato는 주석자마다 작업 내용을 파일에 저장하고, 프로젝트 데이터는 SQLite 데이터베이스에 보관합니다. 서버가 실행 중일 때 SQLite 파일을 복사하면 최근 작업이 빠질 수 있으므로, 데이터를 회수할 때는 SQLite 자체의 백업 명령을 써야 합니다.
흔한 연구 상황에 맞는 호스트
어떤 호스트가 맞는지는 연구 기간, 비용을 내는 사람, 소속 기관이 이미 서버를 운영하는지에 따라 달라집니다. 아래 표는 흔한 상황마다 맞는 호스트를, 각 대상의 기본 크기에 대해 Potato가 출력하는 월 비용과 함께 보여 줍니다.
| 상황 | 호스트 | 월 비용 | 가이드 |
|---|---|---|---|
| AWS 계정이 있는 연구 | AWS Lightsail, 2 GB | $12 | AWS Lightsail |
| 예산이 없는 미국 기관의 연구 | Jetstream2 | ACCESS 할당이 있으면 무료 | Jetstream2 |
| 가장 낮은 가격으로 하는 연구 | Hetzner Cloud, 4 GB | 약 €6 | Hetzner, Vultr, Linode |
| 공개 데모, 또는 이미 Hugging Face를 쓰는 연구실 | Hugging Face Docker Space | PRO 또는 Team 플랜 | Hugging Face Spaces |
| 몇 사람과 한나절 동안 하는 파일럿 | potato share를 쓰는 내 노트북 | 무료 | Potato를 로컬 또는 클라우드에서 실행하기 |
| 소속 기관이 이미 운영하는 서버 | 리버스 프록시 뒤에 둔 Docker 이미지 | Potato 쪽 비용 없음 | 프로덕션 설정 |
처음 세 가지는 재시작해도 디스크가 남는 가상 머신이므로, 몇 주 동안 이어지는 연구에서는 이들이 기본 선택지입니다. Hugging Face Space는 재시작할 때마다 디스크를 잃기 때문에, Potato는 주석을 5분마다 비공개 Hugging Face 데이터셋에 백업하고 Space가 시작될 때 복원합니다. Potato를 로컬 또는 클라우드에서 실행하기에는 Fly, Railway, Render, Heroku를 포함한 13개 클라우드 대상이 모두 나와 있습니다.
새 호스트에서 쓰는 potato deploy
potato deploy up은 파일럿에서 쓴 설정을 받아, 원래라면 사람이 손으로 해야 할 일을 대신 합니다. VM에서는 머신을 만들고, 포트 22, 80, 443만 열고, Docker와 Caddy 웹 서버를 설치하고, Let's Encrypt 인증서를 받고, 프로젝트를 업로드하고, Potato를 서비스로 시작합니다. 먼저 호스트에 맞는 pip extra(그 호스트에 배포하는 데 필요한 선택 의존성)를 설치한 다음, 호스트가 읽는 방식 그대로 설정을 점검하십시오.
pip install 'potato-annotation[deploy-aws]'
potato deploy check myproject/config.yaml --provider aws
potato deploy up myproject/config.yaml --provider aws --dry-runpotato deploy check는 설정 오류를 보고하고, 내 컴퓨터에서만 찾을 수 있는 경로를 찾아냅니다. --dry-run에는 클라우드 계정이 필요 없으며, 배포가 만들 모든 리소스, 월 비용, 로그인할 수 있는 사람을 출력합니다. 공개 주소에서 공개 가입이 허용되어 있으면 경고 D003으로 알려 줍니다. 배포하려면 같은 명령을 --dry-run 없이 실행합니다. Potato는 계획을 다시 보여 주고, 확인할 때까지 아무것도 만들지 않으며, 마지막에 주석자에게 보낼 URL을 출력합니다.
배포는 호스팅과 관련된 설정만 바꿉니다. 디버그 모드를 끄고, 재시작 후에도 세션을 유지하며, 워커 프로세스 하나로 실행합니다. Potato는 항목 풀과 배정 대기열을 메모리에 두기 때문에, 두 번째 프로세스가 있으면 같은 항목을 두 번 나눠 주게 됩니다. user_config, authentication, require_password는 작성한 그대로 둡니다. 배포용 관리자 키를 생성해 설정 옆의 .potato/secrets.json에 저장하며, 이 키로 /admin의 관리자 대시보드를 열 수 있습니다.
소속 기관이 이미 운영하는 서버에서 실행하는 Potato
소속 기관이 이미 서버를 운영한다면, 새 호스트를 만드는 대신 공개된 Docker 이미지를 그 서버의 리버스 프록시 뒤에서 실행하십시오. nginx 같은 리버스 프록시가 인증서를 갖고 요청을 Potato로 전달합니다. 프로덕션 설정에 Docker Compose 파일, nginx 구성, gunicorn 설정이 있습니다. gunicorn은 워커 하나로 두고 동시 처리는 스레드를 늘려 확보하십시오. 두 번째 워커 프로세스는 같은 항목을 두 번 나눠 주기 때문입니다.
Potato의 backup 블록은 데이터 사본을 그 서버 밖에 둡니다. 주석 출력과 프로젝트 데이터베이스의 스냅숏을 기본적으로 5분마다 Hugging Face 데이터셋이나 S3 호환 버킷에 복사하고, 서버가 빈 디스크로 시작되면 이를 복원합니다. 설정에 이 블록을 추가하고, hosting extra를 설치한 뒤, 서버 환경에 HF_TOKEN을 설정하십시오.
backup:
schedule_minutes: 5
restore_on_boot: true
sinks:
- type: huggingface
repo_id: lab/pilot-annotations데이터셋이 없으면 Potato가 비공개 저장소로 만듭니다. 복원은 주석과 함께 계정 목록도 되살리므로 주석자는 같은 비밀번호로 로그인할 수 있고, 디스크에 이미 있는 주석은 절대 덮어쓰지 않습니다.
상태 확인과 데이터 회수
potato deploy status는 서버가 실행 중인지, 인증서가 정상인지 보고합니다. 도메인 이름이 없는 VM에서는 인증서가 IP 주소에 대해 발급되며 유효 기간은 약 6일입니다. 인증서는 자동으로 갱신되므로, 연구를 지켜보는 사람 없이 운영한다면 며칠마다 상태를 확인하거나, 서버를 가리키는 DNS 레코드를 만들고 --domain을 지정하십시오. potato deploy logs myproject/config.yaml -f는 서버 로그를 계속 따라가며 보여 주고, 관리자 대시보드에는 주석자가 작업하는 동안 진행 상황, 처리량, 주석자 간 일치도가 표시됩니다.
연구가 끝나면 호스트를 삭제하기 전에 데이터를 pull하십시오.
potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yamlpull은 주석 출력과 프로젝트 데이터베이스를 새 potato-pull-<name>-<timestamp> 디렉터리에 복사하고 도착한 내용을 확인합니다. destroy는 한 번도 pull하지 않은 배포를 삭제하지 않으며, 파일을 하나도 받지 못한 pull은 pull로 치지 않습니다. 무엇이든 삭제하기 전에 pull한 디렉터리를 열어 마지막 주석이 들어 있는지 확인하십시오.
더 읽을거리
- Potato를 로컬 또는 클라우드에서 실행하기: 모든 클라우드 대상과 백업 플래그
- 프로덕션 설정: 직접 운영하는 서버에서 쓰는 gunicorn, Docker, nginx
- Prolific과 MTurk에서 연구 진행하기: 배포한 작업으로 크라우드워커를 보내는 방법
- 머신러닝을 위한 어노테이션 내보내기: pull한 데이터를 학습용 파일로 만드는 방법