Potato 연구를 온라인에 올리기

Potato 연구를 온라인에 올린다는 것은 주석자가 웹 주소로 접속할 수 있는 컴퓨터에서 작업을 실행하고, 연구가 진행되는 동안 주석을 안전하게 보관하고, 끝나면 주석을 내려받는다는 뜻입니다. 소속 기관의 IT 팀에 요청하는 방법과 동료가 준비한 배포 버튼을 누르는 방법은 내 쪽에서 터미널이 필요 없는 두 가지 경로입니다.

연구를 배포한다는 것은 직접 만든 Potato 작업을 내 컴퓨터에서 서버로 옮긴다는 뜻입니다. 서버는 계속 켜져 있고 인터넷에 연결된 컴퓨터입니다. 그러면 주석자가 어디서든 웹 브라우저로 작업을 열고, Potato는 주석자가 작업하는 동안 각 답을 서버에 저장합니다. Study Designer의 미리보기는 Potato를 내 브라우저 안에서만 실행하므로 다른 사람은 그 사본에 접속할 수 없습니다. Designer에서 만든 연구도 아래 경로 중 하나가 필요합니다.

모든 경로는 같은 프로젝트 폴더에서 출발합니다. Study Designer의 Download project (.zip) 버튼은 config.yaml(작업을 설명하는 파일), 샘플 데이터 파일, README를 저장합니다. 샘플 파일에는 자리 표시용 항목 세 개가 들어 있습니다. 배포하기 전에 샘플 파일을 내 항목으로 바꾸십시오. 형식은 데이터 형식에 설명되어 있습니다.

경로 고르기

경로마다 기술 작업을 누가 하는지, 서버 비용이 얼마인지, 연구를 얼마나 오래 열어 둘 수 있는지가 다릅니다. 아래 비용은 2026-11-04 기준 호스트의 가격표와 Potato 자체의 추정치이며, 대기 시간은 측정값이 아니라 대략적인 안내입니다.

어느 쪽이 좋을지 모르겠다면 IT 팀부터 시작하십시오. 기관 안에 있는 서버는 데이터를 기관이 이미 관리하는 장비에 두고, IT 팀이 보안 업데이트와 백업을 맡을 수 있습니다.

IT 또는 연구 컴퓨팅 팀에 요청하기

많은 대학과 병원에는 연구를 위해 웹 애플리케이션을 호스팅해 주는 연구 컴퓨팅 서비스가 있습니다. 이런 팀에게 Potato는 평범한 웹 애플리케이션이며, 팀은 Potato에 필요한 것을 한 페이지로 요약한 내용에서 시작할 수 있습니다.

1. Study Designer에서 프로젝트를 내려받고 샘플 데이터 파일을 내 항목으로 바꿉니다.
2. IT 팀에 프로젝트 폴더와 IT 팀을 위한 Potato 서버 요구 사항 링크를 보냅니다.
3. 팀에 주석자가 누구인지, 몇 명이 참여하는지, 연구가 얼마나 오래 이어지는지 알립니다.
4. 주석자가 어떻게 로그인할지 알립니다. 기관 계정이 있는 동료는 기관이 이미 운영하는 로그인인 싱글 사인온을 쓸 수 있고, 외부 주석자는 내가 목록으로 만든 사용자 이름을 쓸 수 있습니다.
5. 항목이나 답에 개인 정보나 민감한 정보가 들어 있는지 알리고, 연구가 따르는 윤리 승인을 밝힙니다.
6. 팀에 연구의 웹 주소, Potato의 관리자 대시보드를 여는 관리자 키, 백업 계획, 연구가 끝날 때 데이터를 넘겨받는 방법을 요청합니다.

주소가 도착하면 그 주소를 누구에게 보내기 전에 주석자를 초대하기 전에를 차례로 확인하십시오.

동료가 준비한 배포 버튼 누르기

배포 버튼은 코드 저장소 페이지에 있는 링크로, 호스팅 회사의 서버에 Potato 작업의 사본을 만드는 일을 브라우저의 양식만으로 처리합니다. git과 터미널을 쓰는 동료가 프로젝트 폴더가 들어 있는 저장소에서 potato deploy button 명령으로 버튼을 한 번 만듭니다. 그 동료에게는 Potato를 로컬 또는 클라우드에서 실행하기 페이지를 보내십시오.

이 버튼은 요금이 서로 다른 세 호스트에서 동작합니다.

• Render는 결제 수단 없이 무료 플랜으로 연구를 실행합니다. 무료 Render 서비스는 방문자가 없는 채로 15분이 지나면 잠들고, 다음 주석자가 도착하면 깨어나는 데 약 1분이 걸립니다.
• Heroku는 버튼이 만드는 서버에 월 $7를 청구합니다. Heroku는 앱을 만들기 전에 확인된 계정을 요구하며, 보통 신용카드로 확인합니다.
• AWS는 Lightsail 서버를 월 $12에 실행합니다. AWS 버튼은 공개 저장소에서 작업을 읽으므로, 공개해도 되는 항목에만 알맞습니다.

Render와 Heroku는 서버가 재시작될 때마다 서버의 디스크를 지웁니다. 그래서 버튼은 주석을 5분마다 데이터와 모델을 공유하는 사이트인 Hugging Face의 비공개 데이터셋에 복사하고, 서버가 시작될 때마다 주석을 다시 복사해 옵니다. 그 데이터셋의 이름은 버튼을 누를 때 내가 정하며, 데이터셋은 내 계정에 속합니다.

버튼을 누르기 전에 세 가지를 준비하십시오.

• 호스트(Render 또는 Heroku)의 계정
• 쓰기 권한이 있는 액세스 토큰이 딸린 무료 Hugging Face 계정, 토큰은 huggingface.co/settings/tokens에서 만듭니다
• 저장소가 비공개라면 저장소에 대한 접근 권한, Heroku는 비공개 저장소를 쓰려면 GitHub 계정을 연결하라고 요구합니다

그다음 배포합니다.

1. 저장소의 README에 있는 버튼을 누르고 호스트에 로그인합니다.
2. 앱의 이름을 정합니다. 이 이름이 연구 웹 주소의 일부가 됩니다.
3. POTATO_BACKUP_HF_REPO에 Hugging Face 사용자 이름과 연구 이름으로 이루어진 데이터셋 이름을 입력합니다. 예를 들면 your-username/my-study-annotations입니다. 이름이 새것이면 Potato가 데이터셋을 만들고 비공개로 설정합니다.
4. HF_TOKEN에 Hugging Face 토큰을 붙여 넣습니다. 나머지 칸은 모두 버튼이 채워 둔 값 그대로 둡니다.
5. 배포를 시작하고 호스트가 앱이 실행 중이라고 알릴 때까지 기다립니다. 호스트가 보여 주는 웹 주소를 엽니다.
6. 관리자 키를 찾습니다. 배포하는 동안 호스트가 만든 비밀번호입니다. Heroku에서는 앱의 Settings 탭에 있는 POTATO_ADMIN_API_KEY 항목이고, Render에서는 서비스의 Environment 페이지에 있는 같은 항목입니다.
7. 연구 주소 끝에 /admin을 붙여 열고 관리자 키를 붙여 넣어 관리자 대시보드를 엽니다.

작업, 항목, 주석자 목록은 저장소가 정합니다. 이후의 변경은 버튼을 만든 동료를 거쳐야 하므로, 버튼을 누르기 전에 작업을 끝내십시오. 항목을 공개해도 되는 경우가 아니라면 저장소를 비공개로 유지하십시오.

내 컴퓨터에서 링크 공유하기

내 컴퓨터는 오후 한나절 동안의 파일럿을 제공할 수 있습니다. 주석자는 임시 웹 링크를 열고, 주석은 내 프로젝트 폴더에 저장되며, 명령을 닫으면 링크가 작동을 멈춥니다. 이 경로에는 명령을 입력하는 프로그램인 터미널이 필요합니다. Mac에서는 Terminal(응용 프로그램의 유틸리티 폴더)이고, Windows에서는 PowerShell(시작 메뉴에서 "PowerShell" 검색)입니다.

1. python.org/downloads에서 Python 3.9 이상을 설치합니다. Windows에서는 Python install manager를 내려받습니다. Mac에서는 macOS 설치 프로그램을 내려받습니다.

2. 터미널을 열고 Potato를 설치합니다. Mac에서는 다음을 입력합니다.

   bash복사

   python3 -m pip install potato-annotation

   Windows에서는 다음을 입력합니다.

   powershell복사

   py -m pip install potato-annotation

3. Study Designer에서 내려받은 프로젝트의 압축을 풉니다. Mac에서는 .zip 파일을 더블클릭합니다. Windows에서는 파일을 마우스 오른쪽 버튼으로 눌러 Extract All을 고릅니다. 샘플 데이터 파일을 내 항목으로 바꿉니다.

4. 터미널을 프로젝트 폴더로 옮기고 Potato를 시작합니다. 아래 폴더 이름은 예시이므로 내 폴더의 이름을 쓰십시오. Mac에서는 다음과 같습니다.

   bash복사

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

   Windows에서는 다음과 같습니다.

   powershell복사

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

5. 브라우저에서 http://localhost:8000을 엽니다. 이 주소에는 내 컴퓨터만 접속할 수 있습니다. Potato를 멈추려면 터미널에서 Ctrl-C를 누릅니다.

6. 다른 사람이 들어올 수 있게 하려면 cloudflared를 설치합니다. Cloudflare의 무료 프로그램이며 계정이 필요 없습니다. Homebrew가 있는 Mac에서는 brew install cloudflared를 실행합니다. Windows에서는 Cloudflare의 다운로드 페이지에서 Windows 설치 프로그램을 내려받습니다.

7. potato start 대신 potato share를 실행합니다.

   bash복사

   python3 -m potato share config.yaml

   Windows에서는 py -m potato share config.yaml을 입력합니다. Potato는 누가 로그인할 수 있는지 출력하고 무엇이든 공개하기 전에 확인을 요청합니다. y를 입력하면 Potato가 주석자에게 보낼 https:// 링크를 출력합니다.

링크는 명령이 실행되는 동안에만 작동합니다. 터미널을 닫거나, 컴퓨터를 절전 모드로 두거나, 네트워크를 바꾸면 링크가 끊기며, 다시 실행하면 새 링크가 출력됩니다. 일부 대학 네트워크는 cloudflared가 만드는 trycloudflare.com 링크를 차단합니다. 주석자가 링크가 차단되었다고 알리면 potato share config.yaml --backend tailscale이 대신 Tailscale을 씁니다. Tailscale에는 무료 계정이 필요합니다. potato share가 No tunnel backend found를 보고하면 Potato가 내 컴퓨터에서 cloudflared를 찾지 못한 것이며, 메시지에 설치 명령이 나열됩니다.

설치는 가상 환경과 선택 기능을 다루고, Potato를 로컬 또는 클라우드에서 실행하기는 potato share를 더 자세히 다룹니다.

명령 하나로 서버 빌리기

potato deploy up은 클라우드 회사에서 서버를 빌리고, HTTPS 인증서(브라우저 주소창의 자물쇠)를 받고, 프로젝트 폴더를 업로드하고, 연구를 시작한 뒤 웹 주소를 출력합니다. 이 명령에는 위의 1단계에서 3단계까지의 터미널 설정, 클라우드 회사의 계정, 그리고 프로그램이 내 계정으로 작업하게 해 주는 비밀번호 같은 키인 API 토큰이 필요합니다. 호스트별 가이드가 계정과 토큰을 처음부터 다룹니다.

모든 호스트가 같은 명령 두 개를 받으며, 호스트별 가이드가 그 호스트의 공급자 이름과 설치 명령을 알려 줍니다. 첫 번째 명령은 계획과 월 비용을 보여 주고 아무것도 만들지 않으며, 두 번째 명령은 확인한 뒤에 서버를 만듭니다.

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

Hugging Face의 Duplicate this Space 버튼은 브라우저에서 Space를 복사하지만, Potato Space의 사본은 원래 소유자의 백업 설정을 그대로 가져오고 원본의 시크릿은 잃습니다. 대신 potato deploy up --provider huggingface로 Potato Space를 배포하십시오.

주석자를 초대하기 전에

어떤 경로를 택했든 연구에 웹 주소가 생기면 이 목록을 한 번 확인하십시오.

• 로그인할 수 있는 사람을 정합니다. 가장 간단한 닫힌 구성은 사용자 이름 목록입니다. Study Designer에서 Allow All Users를 끄고 Authorized Users 아래에 주석자를 한 명씩 추가하십시오. 목록에 있는 주석자는 첫 방문에서 가입할 때 각자 비밀번호를 정하고, Potato는 목록에 없는 사람을 거부합니다. 목록에 있는 사용자 이름을 처음 가입하는 사람이 그 계정을 갖게 되므로, 각 주석자에게 사용자 이름을 직접 보내십시오. 기관 계정은 SSO 및 OAuth 인증을, 크라우드워커는 크라우드소싱 연동을 참고하십시오. Allow All Users를 켜 두면 주소를 찾은 누구나 계정을 만들 수 있습니다. 이 설정은 공개 데모에만 쓰십시오.
• 주석이 어디에 저장되는지 압니다. Potato는 주석자가 작업하는 동안 각자의 답을 주석자별 폴더 안의 user_state.json이라는 파일에 저장합니다. 이 폴더들은 설정이 이름을 부르는 출력 폴더에 있으며, Study Designer는 이 폴더를 output이라고 부릅니다. 내 컴퓨터에서는 이 폴더가 프로젝트 폴더 안에 있습니다. 버튼 배포에서는 Hugging Face 데이터셋이 재시작 뒤에도 남는 사본을 보관합니다. 빌린 서버에서는 potato deploy pull이 이 폴더를 내려받습니다. 기관 서버에서는 서버를 어떻게 백업하는지 IT 팀에 물어보십시오.
• 두 번째 브라우저로 시험합니다. 비공개 창에서 연구 주소를 여십시오. Chrome에서는 Incognito, Safari와 Firefox에서는 Private Window, Edge에서는 InPrivate입니다. 목록에 pilot-test 같은 사용자 이름을 추가하고 그 이름으로 가입해 항목 세 개에 답하십시오. 창을 닫고 다시 로그인해 답이 그대로 있는지 확인합니다. 그다음 관리자 대시보드를 열어 시험용 주석자가 보이는지 확인합니다. 주석자가 휴대전화로 작업할 수 있다면 휴대전화에서도 주소를 열어 보십시오.
• 관리자 키를 비공개로 둡니다. 관리자 키는 /admin의 관리자 대시보드를 엽니다. 대시보드에는 모든 주석자의 답이 보입니다. 내 컴퓨터에서는 /admin을 처음 열 때 Potato가 키를 프로젝트 폴더의 admin_api_key.txt에 저장합니다.
• 초대문을 씁니다. 각 주석자에게 주소, 사용자 이름, 작업에 걸리는 시간, 문제가 생기면 연락할 사람을 보내십시오.

결과 받기

관리자 대시보드는 터미널 없이 결과를 내 컴퓨터로 내려받습니다. /admin을 열고 관리자 키를 입력한 다음 Publish Dataset을 고르십시오. Target에서 Local archive를 고르고, 스프레드시트에는 Data format을 CSV로 설정한 뒤 Publish를 누릅니다. 아카이브가 준비되면 Download archive를 누릅니다.

아카이브에는 각 주석자의 답, 항목, 다수결로 통합한 레이블이 들어 있습니다. 아카이브의 README는 레이블 개수와 주석자 간 일치도를 보고합니다. Anonymize annotators를 해제하지 않으면 주석자 이름은 A1, A2 같은 이름으로 바뀝니다. 설문 응답에는 개인 정보가 들어 있을 수 있으므로, Include survey / phase responses를 선택하지 않으면 설문 응답은 아카이브에 들어가지 않습니다.

터미널에서는 python -m potato.export가 같은 주석을 Potato의 내보내기 형식 중 아무것으로나 폴더에 씁니다.

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

potato deploy up으로 만든 서버에서는 potato deploy pull config.yaml이 데이터베이스를 포함해 서버가 수집한 모든 것을 내려받습니다.

서버 비용이 나가지 않도록 연구 끝내기

무엇이든 지우기 전에 결과를 내려받고, 내려받은 파일을 열어 마지막 주석자의 답이 있는지 확인하십시오. 그다음 경로에 맞게 서버를 종료합니다.

• 내 컴퓨터. 터미널에서 Ctrl-C를 누릅니다. 청구된 비용은 없습니다.
• IT 팀. 팀에 연구가 끝났다고 알리고, 출력 폴더의 사본을 요청하고, 서버의 사본을 얼마 동안 보관하는지 물어봅니다.
• 배포 버튼. Heroku에서는 앱의 Settings 탭에서 앱을 삭제하고, Render에서는 서비스의 Settings 페이지에서 서비스를 삭제합니다. Hugging Face 데이터셋에는 주석의 전체 사본이 들어 있습니다. 백업이 더 이상 필요 없으면 데이터셋의 설정 페이지에서 데이터셋을 삭제합니다.
• 빌린 서버. potato deploy pull config.yaml을 실행하고 내려받은 폴더를 확인한 다음 potato deploy destroy config.yaml을 실행합니다. 데이터를 한 번도 pull하지 않은 서버는 Potato가 삭제를 거부합니다.

자주 묻는 질문

내 연구를 위한 Potato 서버는 어떻게 만듭니까?

주석자가 웹 주소로 접속할 수 있는 컴퓨터에서 작업을 실행하면 Potato 서버가 됩니다. 소속 기관의 IT 팀이 작업을 대신 실행해 줄 수 있고, 동료가 배포 버튼을 준비해 주면 내가 누를 수 있으며, potato share는 노트북에서 파일럿을 제공할 수 있고, potato deploy up은 서버를 대신 빌려 줍니다. 경로 고르기 아래의 표는 비용과 각 경로에 필요한 터미널 작업을 기준으로 경로를 비교합니다.

내 PC에 Potato는 어떻게 설치합니까?

python.org에서 Python 3.9 이상을 설치한 다음, Windows에서는 PowerShell에 py -m pip install potato-annotation을, Mac에서는 Terminal에 python3 -m pip install potato-annotation을 입력합니다. 설치한 뒤에는 Windows에서 py -m potato start config.yaml, Mac에서 python3 -m potato start config.yaml로 작업을 시작합니다. 선택 기능은 설치에서 다룹니다.

이 페이지에서 쓰는 용어

• 서버. 서버는 계속 켜져 있고 인터넷에 연결되어 있어서 다른 사람들이 웹 브라우저로 그 컴퓨터의 프로그램을 쓸 수 있게 하는 컴퓨터입니다.
• URL, 즉 웹 주소. URL은 주석자가 입력하거나 클릭하는 주소이며 https://my-study.example.edu 같은 형태입니다. 도메인은 주소에서 이름에 해당하는 부분이며 여기서는 my-study.example.edu입니다.
• HTTPS. HTTPS는 비밀번호와 답을 포함해 주석자의 브라우저와 서버 사이의 모든 것을 암호화합니다. 브라우저는 HTTPS 주소에 자물쇠를 표시합니다.
• 포트. 포트는 컴퓨터의 번호가 매겨진 출입구입니다. Potato는 설정이 다른 포트를 지정하지 않으면 8000번 포트에서 대기하며, 로컬 주소 http://localhost:8000은 이 번호로 끝납니다.
• 터미널. 터미널은 명령을 입력하는 프로그램이며 Mac에서는 Terminal, Windows에서는 PowerShell이라고 부릅니다.
• 관리자 키. 관리자 키는 Potato의 관리자 대시보드를 여는 긴 비밀번호입니다.
• API 토큰. API 토큰은 Potato의 배포 명령 같은 프로그램이 호스팅 회사에서 내 계정으로 작업하게 해 주는 비밀번호 같은 키입니다.

더 읽을거리

• IT 팀을 위한 Potato 서버 요구 사항, IT 팀에 보낼 페이지
• Potato를 로컬 또는 클라우드에서 실행하기, 모든 호스트, 배포 버튼, 백업
• 주석 서버 배포하기, 긴 연구에 쓸 호스트 고르기
• Docker로 Potato 실행하기, 컨테이너를 실행하는 서버용
• 관리자 대시보드, 연구가 진행되는 동안 진행 상황 보기