🔗 백그라운드 작업(잡)

내보내기·일괄처리·학습·추론처럼 오래 걸리는 작업은 동기로 붙잡지 않고 시작 → 상태 조회 패턴으로 다룹니다. "아까 시킨 작업 어떻게 됐어?", "돌고 있는 잡 멈춰줘" 가 이 페이지입니다. 핵심은 서로 다른 두 잡 시스템의 구분입니다 — 같은 "잡"이라도 조회·중지 도구가 다릅니다.

구분	🔗 async_jobs (Celery)	🧠 agent jobs (Ray)
무엇인가	backend 의 비동기 작업 — 내보내기·일괄처리 등	synapse-agent 로 실행되는 Ray job — 학습·추론·플레이그라운드 등
목록	list_async_jobs	list_agent_jobs
상세	get_async_job	get_agent_job
로그	—	get_agent_job_logs
취소/중지	cancel_async_job	stop_agent_job

불변식 — 미리 알아야 할 것

• 장시간 작업(Import/Export/Training)은 Job 하위형이며 상태 5종(PENDING/RUNNING/DONE/CANCEL/FAILED)으로 움직입니다.
• 동기로 붙잡지 말고 job 패턴 — 시작한 뒤 상태를 조회합니다.
• 두 잡 시스템은 별개입니다 — Celery 잡 도구로 Ray job 을, Ray job 도구로 Celery 잡을 다룰 수 없습니다.

도구 한눈에

도구	무엇을 할 때	쓰기 여부
list_async_jobs	backend 비동기 작업(Celery) 목록·진행 추적	읽기
get_async_job	Celery 잡 1건 진행률·완료 확인	읽기
cancel_async_job	진행 중인 Celery 잡 취소 요청	✏️ 쓰기
list_agent_jobs	Ray job(학습·추론 등) 목록	읽기
get_agent_job	Ray job 1건 상세	읽기
get_agent_job_logs	Ray job 로그(콘솔/이벤트) 조회	읽기
stop_agent_job	실행/대기 중인 Ray job 중지	✏️ 쓰기(confirm)
list_imports	임포트(Upload) 실행 기록 목록 — 어느 컬렉션/프로젝트로 임포트했나	읽기
get_import	임포트 실행 기록 1건 상세	읽기
list_exports	익스포트(Export) 실행 기록 목록 — 무엇을 내보냈나	읽기
get_export	익스포트 실행 기록 1건 상세	읽기
list_pre_annotations	작업데이터/GT 등록(전처리) 실행 기록 목록	읽기
get_pre_annotation	전처리 등록 실행 기록 1건 상세	읽기
list_trains	학습(Train) 실행 기록 목록 — 어떤 실험을 학습했나	읽기
get_train	학습 실행 기록 1건 상세	읽기
list_plugins	플러그인 정의 목록 — category·is_active 필터	읽기
get_plugin	플러그인 1건 상세	읽기
list_plugin_releases	플러그인 릴리즈 목록 — plugin 필터	읽기
get_plugin_release	플러그인 릴리즈 1건 상세	읽기

도구 상세

list_async_jobs

🔗 공용. Celery 기반 backend 비동기 작업(내보내기·일괄처리 등) 목록입니다. 시켜 둔 작업의 진행·완료 상태를 추적할 때 부릅니다. synapse-agent 로 실행되는 Ray job 이 아닙니다 — 그쪽은 list_agent_jobs 를 씁니다.

• 주요 인자: 페이지네이션(page/page_size).
• 함께 보기: 1건 상세는 get_async_job, 취소는 cancel_async_job.

get_async_job

🔗 공용. Celery 기반 backend 비동기 작업 1건 상세 — list_async_jobs 의 id 로 진행률·완료 여부를 확인합니다. Ray job 이 아닙니다 — 그쪽은 get_agent_job 을 씁니다.

• 주요 인자: id (Celery 잡 ID).

cancel_async_job

🔗 공용. 진행 중인 Celery 기반 backend 비동기 작업의 취소를 요청합니다(list_async_jobs 의 id). 참고로 synapse-agent Ray job 은 이 도구가 아니라 stop_agent_job 으로 중지합니다.

• 주요 인자: id (Celery 잡 ID).

list_agent_jobs

🧠 ML. synapse-agent 로 실행되는 Ray job(추론·플레이그라운드 등) 목록입니다. 학습·추론 잡이 어떻게 돌고 있는지 볼 때 부릅니다. Celery 기반 backend 비동기 작업이 아닙니다 — 그쪽은 list_async_jobs 를 씁니다.

• 주요 인자: status (FAILED | PENDING | RUNNING | STOPPED | SUCCEEDED), action, 페이지네이션(cursor/per_page).
• 함께 보기: 1건 상세는 get_agent_job. 추론 잡을 시작하는 쪽은 run_playground.

get_agent_job

🧠 ML. Ray job 1건 상세 — list_agent_jobs 목록의 id(UUID)로 조회합니다. params/progress_record/metrics_record/result 는 대형 자유형 필드라 요약·절단해 보여줍니다.

• 주요 인자: job_id (UUID).
• 함께 보기: 로그는 get_agent_job_logs 를 씁니다.

get_agent_job_logs

🧠 ML. Ray job 의 로그를 조회합니다(mode=console|tail|events, 기본 console). console/tail 은 콘솔 로그 스냅샷을 최근 N 줄(기본 console=200 / tail=50)로 절단해 보여줍니다 — 실시간 스트리밍은 지원하지 않습니다(백엔드 tail_console_logs 는 SSE 전용이라 이 동기 도구로는 안전 호출이 불가해 스냅샷으로 대체). events 는 구조화 이벤트 로그입니다.

• 주요 인자: job_id, mode (console | tail | events), lines (콘솔 줄 수), event/level (events 필터), 페이지네이션(cursor/per_page).
• 함께 보기: 잡 자체 상태는 get_agent_job.

stop_agent_job

🧠 ML. 실행 중이거나 대기 중인 Ray job 을 사용자 개시로 중지합니다. Celery 기반 backend 비동기 작업 취소가 아닙니다 — 그쪽은 cancel_async_job 을 씁니다. 이미 종료된 잡(SUCCEEDED/FAILED/STOPPED)은 거부되며 사유를 그대로 보여줍니다.

• 주요 인자: job_id (UUID).
• 안전장치: 기본은 dry-run 미리보기(소유/권한/상태 게이트만 검증, 미중지) → confirm=true 로 재호출해야 실제 중지됩니다.
• 함께 보기: 대상 잡 확인은 list_agent_jobs / get_agent_job.

플러그인 실행 기록

위 Job(에이전트 잡)은 무엇을 하는 실행인지(임포트·익스포트·전처리·학습)에 따라 도메인 기록으로 감싸집니다. 이 도구들은 Job 상태에 더해 도메인 맥락(대상 컬렉션·익스포트 필터·전처리 플러그인·학습 실험 등)을 함께 보여줍니다. Job 자체의 진행률·콘솔 로그·중지는 위 get_agent_job/get_agent_job_logs/stop_agent_job 로 드릴다운합니다.

임포트(Upload) ≠ 파일 직접 업로드

여기 list_imports/get_import 는 스토리지에서 데이터 컬렉션으로 임포트한 서버측 잡 기록입니다. 로컬 파일 바이트를 올리는 2단계 직접 업로드는 prepare_data_upload/finalize_data_upload 입니다.

공통: 상세 응답은 도메인 필드 + 요약된 연결 Job(status/action/completed)을 보여주고, 대형 필드(extra_params·filter·tune_config·best_trial)는 절단 요약합니다. 목록은 커서 페이지네이션이며 created_after/created_before 로 기간을 좁힙니다.

list_imports

🏭 임포트(Upload 플러그인) 실행 기록 목록 — 스토리지에서 데이터 컬렉션으로 데이터를 임포트한 내역입니다. "이 컬렉션은 어디서 임포트됐지?" 를 추적할 때 부릅니다.

• 주요 인자: data_collection · project · storage · status(Job 상태) · created_after/created_before · cursor/per_page.
• 함께 보기: 1건 상세는 get_import, 연결 Job 은 get_agent_job.

get_import

🏭 임포트 실행 기록 1건 상세 — 목록의 id 로 조회. 대상 컬렉션/프로젝트·스토리지 경로·is_recursive·연결 Job 상태를 봅니다.

• 주요 인자: id.
• 함께 보기: Job 로그는 get_agent_job_logs.

list_exports

🏭🧠 익스포트(Export 플러그인) 실행 기록 목록 — 할당작업/정답데이터/작업 산출물을 내보낸 내역입니다.

• 주요 인자: target(assignment|ground_truth|task) · storage · project · status · created_after/created_before.
• 함께 보기: 1건 상세는 get_export.

get_export

🏭🧠 익스포트 실행 기록 1건 상세 — target·필터(filter)·스토리지·경로·save_original_file·연결 Job.

• 주요 인자: id.

list_pre_annotations

🏭🧠 작업데이터/GT 등록(PreAnnotation 전처리) 실행 기록 목록 — 파일 또는 추론으로 task.data(작업데이터) 또는 정답(GT)을 사전 등록한 내역입니다. "이 task.data 는 어느 전처리로 등록됐지?" 를 추적할 때 부릅니다.

• 주요 인자: target(task|gt) · method(file|inference) · pre_processor · status · created_after/created_before. target 미지정 시 둘 다 노출.
• 함께 보기: 등록된 어노테이션은 get_task_data.

get_pre_annotation

🏭🧠 전처리 등록 실행 기록 1건 상세 — method·target·전처리 플러그인(pre_processor)·연결 Job.

• 주요 인자: id.

list_trains

🧠 학습(Train) 실행 기록 목록 — 실험의 신경망 학습(일반/HPO) 내역입니다.

• 주요 인자: experiment · dataset(학습데이터 버전 GTDV) · has_model(결과 모델 유무) · search(이름) · status · created_after/created_before.
• 함께 보기: 1건 상세는 get_train.

get_train

🧠 학습 실행 기록 1건 상세 — 실험·GTDV·신경망 플러그인·is_tune(HPO 여부)·best_trial·연결 Job.

• 주요 인자: id.
• 함께 보기: 결과 모델 계보는 get_model_lineage, 실험은 get_experiment.

플러그인 레지스트리

위 실행 기록(임포트·익스포트·전처리·학습)과 Ray job(plugin_release_id)이 참조하는 원장입니다. 플러그인은 임포트·익스포트·전처리·신경망·스마트툴 등의 정의(코드·카테고리)이고, 릴리즈는 그 버전별 실체(설정 스키마·실행 옵션 양식·작성자)입니다. "이 임포트/릴리즈가 어느 플러그인이지?", "이 신경망 릴리즈의 실행 옵션 양식이 뭐지?" 를 확인할 때 부릅니다.

'최신 릴리즈'는 별도로 주지 않습니다

백엔드가 플러그인마다 "최신 릴리즈"를 목록에 미리 붙여주지 않습니다. 행마다 추가 조회(N+1)하면 비용·지연이 커지므로, list_plugin_releases(plugin=id) 로 직접 좁혀 created/version/is_released 로 판단하세요.

list_plugins

🔗 플러그인(임포트·익스포트·전처리·신경망·스마트툴 등) 정의 목록입니다.

• 주요 인자: category(converter|data_validation|export|neural_net|post_annotation|pre_annotation|smart_tool|upload) · is_active · 페이지네이션(cursor/per_page).
• 함께 보기: 1건 상세는 get_plugin, 릴리즈는 list_plugin_releases.

get_plugin

🔗 플러그인 1건 상세 — 목록의 id 로 조회합니다. code·tenant_id·category 는 등록 후 불변입니다.

• 주요 인자: id.
• 함께 보기: 릴리즈는 list_plugin_releases(plugin=id).

list_plugin_releases

🔗 플러그인 릴리즈(버전별 실체) 목록입니다. plugin 으로 특정 플러그인의 릴리즈만 좁혀 볼 수 있습니다.

• 주요 인자: plugin(id) · debug · 페이지네이션(cursor/per_page).
• 함께 보기: 1건 상세는 get_plugin_release.

get_plugin_release

🔗 플러그인 릴리즈 1건 상세 — 목록의 id 로 조회합니다. config/run_schema/installation_schema/meta/readme 는 대형 자유형 필드라 기본은 절단 요약합니다(토큰 절약).

• 주요 인자: id · expand(절단된 필드 하나를 전체로 받기 — config/installation_schema/meta/readme/run_schema).
• 전체를 봐야 할 때: 요약본으로는 옵션 키·타입·기본값을 알 수 없습니다. expand="<필드명>" 으로 다시 호출하면 지정한 필드만 절단 없이 반환합니다.
• ⚠️ 실행 옵션 양식은 릴리즈마다 위치가 다릅니다: expand="run_schema" 를 먼저 보되, 비어 있으면 expand="config" 로 actions.<액션>.params.ui_schema 를 확인하세요. run_schema 가 {} 이고 실제 옵션은 config 안에 들어 있는 릴리즈가 흔합니다(test 환경 실측). 도구도 run_schema 가 비면 이 안내를 함께 돌려줍니다.
• 함께 보기: 신경망 릴리즈로 추론을 구동하려면 run_playground(plugin_release=id), 전처리 릴리즈의 실행 이력은 list_pre_annotations(pre_processor=id), 이 릴리즈로 돌린 Ray job 은 get_agent_job 의 plugin_release_id 로 역추적합니다.