로컬 API | MLOps Central Platform 매뉴얼

에이전트는 api.host:api.port(기본 0.0.0.0:8600)에 HTTP API 제공. 현장 태블릿의 화면, 같은 LAN 의 다른 프로그램, geo-mlops-edge status 같은 CLI 가 모두 이 API 사용. 엣지 PC 는 보통 화면이 없으므로 장비 상태는 이 API 로 확인.

인증

api.token 이 비어 있으면 인증 없음(기본값). 같은 LAN 내부에서는 누구나 사용 가능. 현장 태블릿마다 토큰을 배포하지 않고도 라인의 수집 상태를 확인하기 위한 기본값.
api.token 을 설정하면 모든 요청에 X-Edge-Api-Token 헤더가 필요하고, 토큰이 틀리면 401 invalid api token 반환.
GET /health 는 토큰 없이 접근 가능(로드밸런서·컨테이너 헬스체크용).

# 토큰 설정 (환경 변수 권장)
GEO_EDGE_API__TOKEN=<your-secret>

curl -H 'X-Edge-Api-Token: <your-secret>' http://edge-pc:8600/api/v1/status

파일(/blobs), push, 추론(/inference) 요청의 본문이 api.max_body_bytes(기본 2 GiB)를 넘으면 413 으로 거부. 인증 없는 API 로 잘못 전송된 업로드 하나 때문에 장비가 정지되는 것을 방지.

엔드포인트

메서드	경로	기능
`GET`	`/health`	동작 여부. 토큰 불필요. `{"status":"ok","version":"0.3.0"}`.
`GET`	`/api/v1/status`	장비·링크·대기량·동기화·모델·수집기·리소스·`attention` 을 한 번에 조회
`GET`	`/api/v1/resources`	cpu / gpu / mem / disk 사용률(%), GPU 별 사용률 `gpus`
`GET`	`/api/v1/queue`	대기 중인 항목. `state`(`pending`·`uploading`·`failed`), `kind`, `limit`(1~500, 기본 50), `offset`.
`DELETE`	`/api/v1/queue/{id}`	항목 하나 삭제
`POST`	`/api/v1/records`	선언 없이 레코드 추가. 본문 `{"kind", "payload", "priority"}`.
`POST`	`/api/v1/blobs`	선언 없이 파일 추가. 본문은 파일 자체. 쿼리 `kind`, `filename`, `priority`, `dataset_id`.
`PUT`	`/api/v1/collectors/{name}/records/{id}`	선언된 push 수집기에 레코드 추가. 본문 `{"payload", "ts"}`. `201` 새로 저장 / `200` 중복.
`GET`	`/api/v1/sync`	업로더 상태
`POST`	`/api/v1/sync:run`	즉시 전송
`POST`	`/api/v1/sync:retry-failed`	`failed` 가 된 항목을 다시 대기 상태로
`GET`	`/api/v1/models`	캐시된 모델과 활성 모델
`POST`	`/api/v1/models/{name}:pull`	내려받기(기본으로 활성화까지). 본문 `{"version", "activate"}`. 실패하면 `502` 와 원인(`detail`).
`POST`	`/api/v1/models/{name}:activate`	이 버전으로 전환. 본문 `{"version"}`.
`DELETE`	`/api/v1/models/{name}?version=`	캐시에서 한 버전 삭제. 삭제 전에 그 이름의 모델을 메모리에서 언로드(다른 버전이 실행 중이어도).
`POST`	`/api/v1/inference`	활성 모델로 이미지 판정(모델과 추론 참고)
`GET`	`/api/v1/settings`	장비 정보, 중앙 주소, 적용 중인 정책, `policy_source`, `data_dir`, 수집기 목록(토큰은 제외하고 `configured` 여부만)
`GET`	`/api/v1/events`	서버 전송 이벤트(SSE): link · sync · queue · model · command …

dataset_id 를 지정한 파일은 중앙에서 조립이 끝나면 그 데이터셋의 파일로 등록되고 웹 업로드와 같은 검증을 거침. 데이터셋이 없거나 다른 테넌트의 데이터셋이면 중앙이 404 반환, 에이전트는 그 파일을 재시도하다가 20번째 실패에서 failed 로 표시. dataset_id 를 지정하지 않은 파일은 데이터셋과 별도로 수집 데이터에 보관.

예시

큐의 실패 항목 조회

curl -s 'http://127.0.0.1:8600/api/v1/queue?state=failed&limit=5'

{
  "items": [],
  "backlog": { "count": 0, "bytes": 0, "oldest_ts": null, "evicted_24h": 0, "by_kind": {} }
}

항목이 있으면 attempts(시도 횟수)와 last_error(마지막 오류)가 함께 반환.

이벤트 구독

curl -N http://127.0.0.1:8600/api/v1/events?history=20

event: <kind>
data: {"kind": "<kind>", "name": "<이벤트 이름>", "ts": "<ISO 시각>", "data": {...}}

접속 직후 최근 이벤트 history 개(기본 20, 최대 200)를 먼저 전송하므로 새로 연 화면이 빈 상태로 대기하지 않음.

설정 확인

curl -s http://127.0.0.1:8600/api/v1/settings

{
  "device": {
    "id": "edge-bench-01",
    "location": "bench",
    "hostname": "edge-pc",
    "os": "Ubuntu 24.04.5 LTS x86_64",
    "agent_version": "0.3.0"
  },
  "central": { "base_url": "https://mlops.example.com", "configured": true },
  "policy": { "revision": 0, "heartbeat_interval_s": 5.0, "commands_poll_s": 10.0 }
}

(일부 필드 생략.) OpenAPI 문서는 에이전트의 /docs 에서 제공.

인증#

엔드포인트#

예시#

큐의 실패 항목 조회#

이벤트 구독#

설정 확인#

인증

엔드포인트

예시

큐의 실패 항목 조회

이벤트 구독

설정 확인