Edge SDK
geo-mlops-sdk 로 현장 장비를 플랫폼에 연결하는 방법
이 장은 현장 장비(엣지 PC)를 Geo-MLOps 에 붙이는 개발자를 위한 것입니다. 공개 PyPI 패키지 geo-mlops-sdk(import 이름 geo_mlops_sdk, 현재 0.2.0, Python 3.10 이상)를 씁니다.
패키지에 든 두 가지
| 무엇 | import | 이럴 때 |
|---|---|---|
에이전트 (geo-mlops-edge) | 쓰지 않음(설정 파일로 돌린다) | 장비에서 서비스로 상시 실행. 로컬 큐·오프라인 누적·업로드·수집기·모델 캐시·로컬 API 를 모두 갖춤 |
클라이언트 CentralClient | geo_mlops_sdk.client | 이미 있는 내 애플리케이션이 중앙 서버 API 를 직접 부를 때 |
대부분은 에이전트 하나로 충분합니다. 에이전트는 코드를 쓰지 않고 edge.yaml 과 환경 변수로 설정합니다.
장비와 중앙 사이의 흐름
엣지 장비 (geo-mlops-edge) 중앙 (Geo-MLOps)
───────────────────────── ────────────────
① 등록 POST /api/v1/edge/register ──▶ 디바이스 '정상'
② 하트비트 POST /api/v1/edge/heartbeat ──▶ CPU·메모리·대기량·수집기 상태
③ 수집 수집기 → 로컬 큐(SQLite) (링크가 끊겨도 계속 쌓임)
④ 동기화 telemetry · inference · uploads ─▶ 수집 데이터·추론 결과·파일 탭
⑤ 명령 GET /api/v1/edge/commands ◀── ping · restart · pull_model …
⑥ 모델 pull GET /api/v1/edge/models/… ◀── 모델 레지스트리
⑦ 추론 기록 로컬 추론 → 큐 → inference ──▶ 추론 결과 탭통신은 늘 장비가 서버를 부르는 방향입니다. 공장 NAT 뒤에 있는 장비에는 서버가 먼저 접속할 수 없습니다. 그래서 명령도 장비가 롱폴(응답이 올 때까지 요청을 열어 두고 기다리는 방식)로 가져갑니다. 모든 호출은 중앙에서 발급한 디바이스 토큰(X-Edge-Token 헤더)으로 인증합니다.
이 장의 페이지
| 페이지 | 내용 |
|---|---|
| 설치 | pip install 과 엑스트라 |
| 5분 시작 | 디바이스 등록 → edge.yaml → 에이전트 실행 → 플릿 화면에서 확인 |
| 설정 레퍼런스 | EdgeSettings 전 필드, 설정 파일 탐색 순서, 환경 변수 |
| 데이터 수집기 | http · push · modbus · watchdir, 커스텀 수집기 |
| 모델과 추론 | 모델 내려받기, 러너, 로컬 추론 API |
| 로컬 API | 장비 안 HTTP API(포트 8600) |
| 명령·정책·보존 | 서버 명령, 정책 탭, 오프라인 누적과 동기화 |
| CentralClient 로 직접 붙이기 | 비동기 클라이언트, 오류 계층, 재시도 |
| 배포 | systemd, Docker, docker compose, 토큰 교체 |
| CLI | geo-mlops-edge 하위 명령 |
| 문제 해결 | 오프라인, 401, 413, 큐 적체 |
함수 시그니처 전체는 Edge SDK API 레퍼런스에 있습니다.