5분 시작

중앙에서 디바이스를 하나 만들고, 장비에서 에이전트를 띄워, Edge Fleet 화면에 정상으로 나타나게 합니다. 이 페이지의 출력은 모두 실제로 실행한 결과입니다. 토큰과 호스트 이름만 가렸습니다.

준비물:

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

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

등록 직후 디바이스는 연결 대기 상태입니다. 장비가 첫 하트비트를 보내야 정상 이 됩니다.

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 로 답하고 큐에 넣지 않습니다. 이미지를 /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": null, "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 가 0 이면 모두 중앙으로 보낸 것입니다.

5. 플릿 화면에서 확인#

파일 탭에는 watchdir 로 올린 파일이, 추론 결과 탭에는 장비에서 돌린 추론이 쌓입니다(모델과 추론).

멈추기#

Ctrl-C(또는 SIGTERM)로 멈춥니다. 보내던 청크(파일 조각)를 마저 보내고, 보내려고 꺼내 둔 큐 항목을 큐에 되돌리고, DB 를 닫은 뒤 종료합니다.

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

하트비트가 끊기고 3분(서버 기본값)이 지나면 디바이스는 비정상 으로 바뀝니다. 운영에서는 배포의 systemd 유닛이나 컨테이너로 상시 실행합니다.