English

5분 시작

디바이스 등록, 에이전트 실행, Edge Fleet 화면의 '정상' 상태 확인

필요 권한: 설정ADMIN

중앙에 디바이스를 만들고 장비에서 에이전트를 실행해, Edge Fleet 화면에 정상으로 표시되게 하는 절차.

준비물:

  • 설치를 마친 장비(개발 PC 도 가능)
  • 테넌트 ADMIN 계정(디바이스 등록에 설정ADMIN 권한 필요)
  • 장비에서 중앙 API 주소(예: https://mlops.example.com)로 향하는 HTTPS 연결

1. 중앙에서 디바이스 등록

  1. 왼쪽 메뉴 Edge Fleet 을 열고 오른쪽 위 디바이스 등록 클릭.
  2. ① 디바이스 ID 에 장비 이름 입력(예: edge-bench-01). 최대 64자. 에이전트는 device.id 에서 영문·숫자·.·_·- 외 문자를 - 로 치환하므로, 장비 설정과 일치시키려면 이 문자만 사용. 위치는 선택 사항. ② 토큰 스코프는 기본값으로 다섯 가지 모두 활성화. 확실하지 않으면 기본값 유지. ③ 등록 클릭.
    디바이스 등록 대화상자: ① 디바이스 ID ② 토큰 스코프(기본값은 모두 활성화) ③ 등록
  3. 등록 완료 창에 토큰이 한 번만 표시. 복사 버튼으로 복사해 안전한 곳에 보관. 창을 닫으면 다시 확인 불가. 분실하면 디바이스 상세의 토큰 관리 에서 회전 을 눌러 새 토큰 발급 필요.

등록 직후 디바이스는 연결 대기 상태. 장비가 첫 하트비트를 전송해야 정상 으로 전환.

스코프화면 이름허용하는 호출
telemetry:write텔레메트리하트비트, 수집 레코드 전송
inference:write추론추론 결과 전송
container:pull컨테이너모델 컨테이너 이미지 조회
models:read모델모델 목록·버전·아티팩트 내려받기
data:write파일파일(이미지 등) 청크 업로드

2. 장비에 설정 파일 작성

토큰은 파일이 아니라 환경 변수에 저장. 설정 파일은 저장소나 백업에 포함되기 쉽기 때문.

# /etc/geo-mlops/edge.env  (chmod 600)
GEO_EDGE_CENTRAL__TOKEN=<device-token>
# /etc/geo-mlops/edge.yaml
central:
  base_url: https://mlops.example.com   # 중앙 API 주소

device:
  id: edge-bench-01        # 화면의 디바이스 ID 와 맞춰 두면 헷갈리지 않는다
  location: bench

data_dir: /var/lib/geo-mlops-edge   # 큐·파일·모델 캐시 저장 위치

api:
  host: 127.0.0.1          # 현장 태블릿에서 볼 거면 0.0.0.0
  port: 8600

# 시험 중에는 짧게. 운영은 기본값(30초 / 25초)을 쓴다
heartbeat_interval_s: 5
commands_poll_s: 10

collectors:
  # 다른 프로그램이 로컬 API 로 레코드를 전송하는 수신 경로
  - type: push
    name: robot-1
    priority: 60
    options:
      kind: robot

  # 카메라가 떨군 JPEG 를 파일로 올린다
  - type: watchdir
    name: cam-0
    priority: 20
    options:
      path: /data/incoming
      pattern: "*.jpg"

3. 에이전트 실행

set -a; . /etc/geo-mlops/edge.env; set +a
geo-mlops-edge --config /etc/geo-mlops/edge.yaml run

몇 초 안에 다음 로그가 출력되면 성공.

INFO    geo_mlops_sdk.edge.daemon: starting geo-mlops-edge (data_dir=/var/lib/geo-mlops-edge, central=https://mlops.example.com)
INFO    geo_mlops_sdk.edge.runtime: edge runtime started as edge-bench-01
INFO:     Uvicorn running on http://127.0.0.1:8600 (Press CTRL+C to quit)
INFO    geo_mlops_sdk.edge.link: link offline -> probing
INFO    geo_mlops_sdk.edge.link: link probing -> online
INFO    httpx: HTTP Request: POST https://mlops.example.com/api/v1/edge/register "HTTP/1.1 200 OK"
INFO    geo_mlops_sdk.edge.runtime: registered with Central as edge-bench-01 (ACTIVE)
INFO    httpx: HTTP Request: POST https://mlops.example.com/api/v1/edge/heartbeat "HTTP/1.1 200 OK"

링크 상태는 offline → probing → online 으로 전환. 연속 두 번 성공해야 online 이 되므로(link.online_after_ok) 첫 등록까지 1~2초 소요.

4. 데이터 입력

다른 터미널에서 push 수집기로 세 건의 레코드 입력 후 같은 id 로 한 번 더 전송.

for i in 1 2 3; do
  curl -s -X PUT http://127.0.0.1:8600/api/v1/collectors/robot-1/records/evt-$i \
       -H 'content-type: application/json' \
       -d "{\"payload\": {\"step\": $i}}" -w ' %{http_code}\n'
done
curl -s -X PUT http://127.0.0.1:8600/api/v1/collectors/robot-1/records/evt-1 \
     -H 'content-type: application/json' -d '{"payload": {"step": 1}}' -w ' %{http_code}\n'
{"id":"robot-1:evt-1","kind":"robot","duplicate":false} 201
{"id":"robot-1:evt-2","kind":"robot","duplicate":false} 201
{"id":"robot-1:evt-3","kind":"robot","duplicate":false} 201
{"id":"robot-1:evt-1","kind":"robot","duplicate":true} 200

네 번째 요청은 같은 id 가 아직 큐에 있으면 200 과 duplicate: true 를 반환하고 큐에 추가하지 않음. 이미 중앙으로 전송한 뒤라면 201 반환, 단 중앙은 같은 id 를 한 번만 저장. 이미지를 /data/incoming 에 복사하면 cam-0 수집기가 파일로 업로드.

에이전트의 현재 상태 확인.

geo-mlops-edge --config /etc/geo-mlops/edge.yaml status
{
  "device": {
    "id": "edge-bench-01",
    "location": "bench",
    "hostname": "edge-pc",
    "os": "Ubuntu 24.04.5 LTS x86_64",
    "agent_version": "0.2.0",
    "registered": true
  },
  "link": { "state": "online", "latency_ms": 4.26, "error": "" },
  "sync": { "state": "idle", "last_error": "", "denied": null },
  "backlog": { "count": 0, "bytes": 0, "evicted_24h": 0, "by_kind": {} },
  "collectors": [
    { "name": "robot-1", "type": "push", "state": "running", "error": null },
    { "name": "cam-0", "type": "watchdir", "state": "running", "error": null }
  ],
  "attention": []
}

(일부 필드 생략.) backlog.count 는 아직 전송하지 않은 항목 수. failed 상태인 항목은 포함하지 않으므로 geo-mlops-edge queue --state failed 로 별도 확인.

5. 플릿 화면에서 확인

  1. Edge Fleet 목록에서 ① 새 디바이스가 정상 으로, 대기 0, 동기화 대기 로 표시.
    Edge Fleet: ① 에이전트가 연결된 디바이스는 상태 '정상', 대기 0, 동기화 '대기'로 표시된다
  2. 행을 누르면 상세 화면 표시. ① SDK·에이전트 버전 ② 누적 데이터와 마지막 전송 시각 ③ 장비의 로컬 모델 ④ 수집기별 상태 표시.
    디바이스 상세 개요: ① SDK·에이전트 버전 ② 쌓인 데이터와 동기화 ③ 로컬 모델 ④ 수집기 상태
  3. 레코드 탭에 방금 입력한 레코드가 종류(robot, http …)별로 표시. ① 종류 필터로 범위 축소.
    레코드 탭: 수집기가 전송한 레코드가 종류(kind)별로 기록된다. ① 종류 필터

파일 탭에 watchdir 로 업로드한 파일, 추론 결과 탭에 장비에서 실행한 추론 결과 기록(모델과 추론).

파일 탭: watchdir 수집기가 업로드한 파일과 조각(청크) 전송 상태

중지

Ctrl-C(또는 SIGTERM)로 중지. 전송 중단, 처리 중이던 큐 항목을 대기 상태로 복귀, DB 를 닫은 뒤 종료. 전송이 중단된 파일은 다음 실행 시 중앙이 이미 수신한 청크(파일 조각)를 건너뛰고 이어서 전송.

INFO:     Finished server process [2063519]
INFO    geo_mlops_sdk.edge.runtime: edge runtime stopped

하트비트가 중단되고 3분(서버 기본값)이 지나면 디바이스는 비정상 으로 전환. 운영 환경에서는 배포의 systemd 유닛이나 컨테이너로 상시 실행.

2026-10-02 기준 플랫폼으로 작성

© MLOps Central Platform