IF-03 조회 서비스 (JBNU FacOS 테스트베드)
JBNU 의 FacOS 테스트베드다. IF-03 데이터 소비 규약에 따라 저장된 제조 데이터를 조회·스냅샷·내보내기 한다.
모든 데이터 API 는 접근 토큰(Authorization: Bearer <토큰>)이 필요하다. 권한(현장, 데이터셋 × 목적)은 토큰에 담겨 있다.
| 문서 | 내용 |
|---|---|
| 아키텍처 | 시스템 구성, 데이터 흐름, 시각 정렬(시간 지연 계산), 저장, 조회 서비스 — 이 페이지 아래 |
| SDK 매뉴얼 | 파이썬 SDK databahn 설치·사용법·예제 |
| API 명세 | 엔드포인트, 요청·응답 필드, 오류 코드, 규약 대응 |
| 대화형 API | 브라우저에서 직접 호출 (Swagger UI). 기계용 명세: /openapi.json |
| SDK 내려받기 | wheel 패키지, Foxglove 이미지 변환 확장(.foxe) |
| /healthz | 서비스·카탈로그 자동 동기화 상태 |
SDK 설치
pip install "https://if03.data-bahn.com/sdk/databahn-0.4.1-py3-none-any.whl"
from databahn import Fabric
fab = Fabric("https://if03.data-bahn.com", api_key="<접근 토큰>")
b = fab.read(dataset_id="plab-testbed-cell01", start="2026-11-16T17:53:00+09:00",
end="2026-11-16T17:54:00+09:00", purpose="analysis")
시스템 아키텍처와 구현 내용
SO-ARM101 로봇팔(리더·팔로우)과 카메라 두 대에서 나오는 제조 데이터를 시간 동기화·정합 규약(TS-01~06) 에 맞춰 정렬·기록하고, IF-03 데이터 소비 규약 에 맞춰 조회·내보내기까지 제공하는 테스트베드다. 목적은 두 규약의 구조를 실제 장치와 실제 데이터로 검증하는 것이다.
1. 데이터가 흐르는 순서
- 장치 드라이버(LeRobot, OpenCV)로 팔과 카메라를 읽는다.
- 수집기가 리더암 관절을 읽어 팔로우암에 명령을 보내고(원격 조종), 받은 순간의 컴퓨터 시각(
ts_gateway)과 채널별 번호(seq)를 시각 헤더에 담아 protobuf 메시지로 MQTT 에 발행한다. - MQTT 브로커가 메시지를 셀 로거에 전달한다. QoS1·지속 세션이라 셀 로거가 잠시 늦어도 잃지 않는다.
- 동기 에이전트가 1분마다 NTP 로 컴퓨터 시계가 표준시와 얼마나 다른지 재서 같은 브로커로 보낸다. 시계를 고치지는 않는다.
- 셀 로거가 메시지를 받은 시각(
ts_ingest)을 찍고, 옆의 시간 지연 계산기(사이드카)에 시각 헤더와 시계 오차 측정값을 넘긴다. 계산기는 장치 지연을 빼 실제 사건 시각을 추정하고, 그 추정이 얼마나 틀릴 수 있는지(불확도)와 등급을 돌려준다. 셀 로거는 그 결과로 MCAP 파일에 기록하고, 같은 결과를 붙여 정렬 스트림(aligned/<채널>)으로 곧바로 다시 발행한다. 모델의 실시간 입력은 이 스트림이다. - 파일이 닫히면(10분 경계, 30초 무입력, 2 GB, 종료) 업로더가 중앙 패브릭의 수집 경로에 올린다. 덮어쓰지 않고, SHA-256 으로 확인한다.
- 서버의 조회 서비스가 30초마다 수집 경로를 처리한다: 파일을 검사·색인해 저장소와 카탈로그(PostgreSQL)에 등록하고, 실패한 파일은 격리해 사유를 돌려준다.
- 소비자는 Python SDK, Foxglove(MCAP 내보내기), REST API 로 데이터를 쓴다. 녹화 후 조회까지 최대 약 11분.
- IF-20(그림 오른쪽, 같은 EKS)은 모델을 다룬다. 학습 Job 이 스냅샷으로 학습해 MLflow 에 학습 이력을 남기고 IF-20 에 등록하면, IF-20 이 서명해 Triton 으로 배포하고 추론을 받는다. 참조 전달 추론은 IF-20 이 호출자 대신 IF-03 에서 읽는다. MLflow 는 인증 모드라 쓰기는 학습 Job 과 IF-20 만 할 수 있다. 자세한 것은 docs/if20-phase1-design.md, API 는 API 명세 10장.
2. 셀 — 로컬 (수집에서 데이터 레이크까지)
| 구성 요소 | 하는 일 | 구현 요점 |
|---|---|---|
| 장치 | 리더암·팔로우암 (Feetech STS3215 서보 6개씩), 손목·탑 카메라 (UVC) | 관절 위치·명령·온도·전압, JPEG 640×480 30 fps 영상 |
| 장치 드라이버 | 팔·카메라 입출력 | 팔: LeRobot SOLeader/SOFollower (Feetech 서보 버스, USB 시리얼, 60 Hz, 보정은 lerobot-calibrate). 카메라: OpenCV (macOS AVFoundation) |
수집기 collector |
장치 읽기, 원격 조종, 메시지 발행 | 모든 메시지에 시각 헤더(TS-03): 채널 ID, seq, ts_gateway, 시각 근거, 시계 동기 상태, 프로파일 버전. 관절은 읽기 요청 직전 시각도 함께 기록. 작업자가 입력한 작업 시작·끝(에피소드)도 발행. 장치가 끊기면 안전하게 멈춘다 |
| MQTT 브로커 | 셀 단위 메시지 전달 | Mosquitto(로컬), QoS1, 지속 세션. 시각을 만들지 않는다 |
동기 에이전트 sync_agent |
컴퓨터 시계 오차 측정 (TS-05) | 1분마다 NTP 측정 → ntp_state(오프셋, 오차 한계, 상태) 발행. 시계를 고치지 않는다 (3.4) |
셀 로거 cell_logger |
받기·기록·정렬 스트림 | 받은 시각 ts_ingest 기록, 시각 계산은 계산기에 묻는다. 계산 결과를 붙여 곧바로 정렬 스트림 발행(재정렬 버퍼·파일 닫기를 기다리지 않음). 2초 재정렬 버퍼로 추정 시각 순서로 쓰고, 10분 파일·묶음별(arm·cam·context·sync) 분리, manifest 작성. 카탈로그에는 쓰지 않는다 |
시간 지연 계산기 align_sidecar |
장치 지연을 빼 실제 시각·불확도·등급 계산 (3장) | 셀 로거 옆 별도 프로세스(사이드카). 로컬 소켓으로 메시지마다 요청·응답. 채널 프로파일, 채널별 seq, 시계 상태를 가진다. 계산은 정렬 엔진(align_engine, 버전을 기록마다 남김) |
업로더 uploader |
수집 경로에 올리기 | 닫힌 파일만, 조건부 쓰기(If-None-Match)로 덮어쓰기 금지, 업로드 전후 SHA-256 대조, 64 MB 넘으면 멀티파트, MCAP 먼저·manifest 마지막. 수집 결과를 받아 로컬 파일을 통과(uploaded/)·격리(rejected/)로 나눈다 |
재정렬 도구 fabric.realign |
계산 근거가 바뀐 구간을 다시 계산 (3.6) | 관리자가 수동으로 실행. 셀 로거와 같은 정렬 엔진. 결과를 업로더가 수집 경로에 올린다 |
채널 시각 프로파일(TS-02)은 채널마다 시각 기준점, 사건 시점, 지연 모델(d, b), 최소 식별 간격, 기대 등급을 적은 파일이다.
계산기는 이 프로파일로 계산하고, 조회 서비스는 같은 프로파일로 품질을 판단한다. 프로파일 사본은 MCAP 안과 S3 _sync/ 에 함께 남긴다.
3. 시각 정렬 — 시간 지연 계산기
3.1 무엇을 계산하나
장치는 자기 시각을 보내지 않는다. 컴퓨터가 데이터를 받은 시각만 안다. 그런데 데이터는 장치에서 컴퓨터까지 오는 데 시간이 걸리므로, 받은 시각은 실제로 측정·촬영한 시각보다 늦다. 계산기는 이 지연을 빼서 실제 시각을 추정하고, 그 추정이 얼마나 틀릴 수 있는지(불확도)를 함께 낸다.
계산 순서 (메시지마다):
- 검사 — 등록된 채널인지, 프로파일 판이 맞는지,
seq가 빠지거나 겹치지 않았는지, 받은 시각이 뒤집히지 않았는지 본다. 문제가 있으면 진단 코드를 붙인다 (3.5). - 실제 시각 추정 —
실제 시각 = 받은 시각(ts_gateway) − d. d 는 그 채널의 평균 장치 지연으로, 미리 실측해 채널 프로파일에 적어 둔 값이다. - 불확도 —
불확도 = b + 시계 오차. b 는 지연이 평균에서 벗어날 수 있는 최대 폭(실측), 시계 오차는 그 시점의 컴퓨터 시계가 표준시와 다를 수 있는 폭이다 (동기 에이전트 측정값, 3.4). - 등급 — 불확도로 정한다: 1 ms 이하 Tier-2, 100 ms 이하 Tier-3, 그보다 크면 Tier-4. 시각을 추정할 수 없으면 Tier-U.
예 (컴퓨터 시계 오차가 17 ms 인 때):
| 받은 시각 | d | 실제 시각 추정 | b | 불확도 | 등급 | |
|---|---|---|---|---|---|---|
| 팔로우 관절 | 12:00:00.1000 | 0.6 ms | 12:00:00.0994 | 5 ms | 5 + 17 = 22 ms | Tier-3 |
| 손목 카메라 프레임 | 12:00:00.1000 | 36 ms | 12:00:00.0640 | 31 ms | 31 + 17 = 48 ms | Tier-3 |
같은 순간에 받았어도 카메라 프레임은 실제로 36 ms 먼저 찍힌 것으로 기록되고, 두 시각은 각각 ±22 ms, ±48 ms 범위 안에서만 믿을 수 있다.
3.2 셀 로거와 계산기 (사이드카)
셀 로거 ── 시각 헤더(채널, seq, ts_gateway, 프로파일 판) + ts_ingest ──▶ 시간 지연 계산기
◀── 실제 시각 추정, 불확도, 등급, 진단 코드, 채널 기본값 ──────
셀 로거 ── 시계 오차 측정값(ntp_state, 시계 튐) ──▶ 시간 지연 계산기 (시계 상태 갱신)
셀 로거 ── 쓰기 직전: 이 메시지가 시계 튐 근처인가? ──▶ 시간 지연 계산기
셀 로거 ── 계산 결과를 붙여 곧바로 ──▶ 정렬 스트림 aligned/<채널> (3.8)
- 계산기는 셀 로거 옆에서 도는 별도 프로세스다. 요청·응답은 로컬 Unix 소켓(길이 + JSON)으로 주고받는다. 영상 같은 메시지 본문은 보내지 않고 시각 헤더만 보낸다.
- 셀 로거가 받은 순서대로 측정값과 메시지를 보내므로, 같은 프로세스에서 계산할 때와 결과가 같다 (자동 테스트로 확인).
- 계산기가 응답하지 않으면 셀 로거는 멈추지 않는다. 그 메시지를 미정렬(Tier-U,
TIM-4241, 사유align_sidecar_unavailable)로 기록하고 1초마다 다시 연결한다. 이렇게 남은 구간은 나중에 재정렬 도구로 다시 계산할 수 있다.
3.3 채널별 지연 모델 (프로파일 0.2.0)
| 채널 | 시각 기준점 | d | b | 불확도 (시계 약 17 ms) | 등급 | 측정 방법 |
|---|---|---|---|---|---|---|
| 팔로우 관절 상태 | 모터 읽기 요청·응답 | 0.6 ms | 5 ms | 약 22 ms | Tier-3 | 요청 직전·응답 직후 시각의 중간을 측정 순간으로, 텔레오퍼레이션 중 왕복 시간 실측 |
| 리더 관절 상태 | 〃 | 0.6 ms | 6 ms | 약 23 ms | Tier-3 | 〃 |
| 팔로우 명령 | 모터 쓰기 | 0.1 ms | 3 ms | 약 20 ms | Tier-3 | 〃 |
| 모터 온도·전압 (1 Hz) | 모터 읽기 | 1.1 ms | 4 ms | 약 21 ms | Tier-3 | 〃 |
| 손목 카메라 | 프레임 수신 → 노출 중앙 | 36 ms | 31 ms | 약 48 ms | Tier-3 | 팔을 움직이며 영상 변화량과 엔코더 이동량의 상호상관이 최대인 지연 (부트스트랩 95% 구간 + 프레임 지터 + 롤링 셔터) |
| 탑 카메라 | 〃 | 40 ms | 35 ms | 약 52 ms | Tier-3 | 〃 |
| 작업자 콘솔 | 사람 입력 | — | — | — | Tier-U | 사람 반응 지연은 잴 수 없어 추정하지 않는다 |
3.4 시계 오차 — 동기 에이전트가 하는 일
동기 에이전트는 컴퓨터 시계를 고치지 않는다 (시계 맞추기는 운영체제의 일이다). 1분마다 NTP 서버와 비교해 "지금 이 컴퓨터 시계가
표준시와 얼마나 다를 수 있는지"를 재서 ntp_state 로 MQTT 에 발행할 뿐이다. 셀 로거가 이것을 받아 계산기에 넘기고,
계산기는 메시지마다 그 시점의 시계 오차를 불확도에 더한다 (3.1 의 3단계). 측정값 자체는 _sync 파일에 근거로 남는다.
시계에 문제가 생기면 이렇게 된다:
| 상황 | 계산기의 판단 | 데이터에 일어나는 일 |
|---|---|---|
| 정상 (최근 3분 안에 측정) | locked — 실측 오차 한계 사용 (1 ms 단위로 올림) | 불확도 = b + 실측 오차. 보통 Tier-3 |
| 시계 오차가 커짐 | locked — 큰 오차 그대로 반영 | 불확도가 커진다. 100 ms 를 넘으면 Tier-4 로 내려간다 |
| 측정이 끊김 (10분까지) | holdover — 마지막 값 + 드리프트(50 ppm × 경과 시간) | 시간이 갈수록 불확도가 커진다, TIM-5031 |
| 10분 넘게 측정 없음 | unlocked — 시계를 믿을 수 없음 | Tier-U (기본 조회에서 빠짐), TIM-5031 |
| 시계가 갑자기 바뀜 (step) | 그 전후 1초는 시각을 믿을 수 없음 | 그 구간 Tier-U, TIM-4231 (셀 로거가 쓰기 직전에 한 번 더 확인) |
시계 튐은 수집기·동기 에이전트가 "실시간 시계 − 단조 시계"가 1 ms 넘게 바뀌는지로 잡는다. 두 시계를 읽는 사이에 다른 스레드가 끼어들면 가짜 튐이 생기므로(2026-11-18 실기에서 2분에 한 쌍, 그때마다 모든 채널 2초가 Tier-U), 단조 → 실시간 → 단조로 읽어 끼어든 측정은 다시 재고, 바뀐 값이 다음 틱에도 남아 있을 때만 튐으로 확정한다. 확정은 한 틱 늦지만 튐 시각은 처음 본 때로 남긴다.
동기 에이전트가 첫 측정을 보내기 전에는 설정값(10 ms)을 쓴다.
3.5 검사와 진단 코드
| 코드 | 뜻 | 처리 |
|---|---|---|
TIM-4011 |
프로파일이 등록되지 않은 채널, 또는 프로파일 판 불일치 | Tier-U |
TIM-4091 / TIM-4092 |
seq 중복 / 건너뜀 (메시지 누락) |
중복은 버리고, 건너뜀은 기록·알림 |
TIM-4221 |
수집기 시각이 셀 로거 수신 시각보다 늦음 (역전) | Tier-U |
TIM-4241 |
지연 미적용 (지연 모델 없음, 또는 계산기 응답 없음) | Tier-U → 재정렬로 복구 가능 |
TIM-4231, TIM-5031 |
시계 튐, 시계 측정 끊김 | 3.4 |
진단 코드는 메시지마다 _align 채널에 남고, 같은 문제가 이어지면 10초 단위로 묶어 알린다.
왜 Tier-3 인가. Tier-2 는 불확도 1 ms 이하다. 지금은 컴퓨터 시계 오차(Wi-Fi NTP 10~20 ms)와 관절의 흔들림 폭(USB 왕복 3~6 ms)이 각각 그보다 크다. 하드웨어 시각 동기(PTP)와 장치 자체 타임스탬프가 있어야 Tier-2 가 된다. Tier-3 는 "수십 ms 안에서 채널끼리 비교 가능"을 뜻하며, 관절 궤적과 영상 프레임을 맞추는 데는 충분하다. 두 사건의 선후는 시각 차가 두 불확도의 합보다 클 때만 판단한다.
3.6 재정렬 도구 — 언제 어떻게
자동으로 돌지 않는다. 정렬 근거가 나중에 바뀌었을 때 관리자가 로컬에서 실행한다.
| 언제 | 예 |
|---|---|
| 지연 모델이 없던 채널에 모델이 생겼을 때 | 새 카메라를 붙여 먼저 기록하고(Tier-U, TIM-4241), 지연을 잰 뒤 정렬 |
| 지연 모델 값을 고쳤을 때 | 카메라 지연을 다시 재서 d·b 가 바뀜 |
| 계산기가 멈춰 미정렬로 기록된 구간 | 3.2 |
uv run python -m fabric.realign plan --channels <채널>... --profiles profiles/channels # 대상 파일·메시지 수 확인
uv run python -m fabric.realign apply --channels <채널>... --profiles profiles/channels # 재정렬본 생성 → 수집 경로 → 수집 검사 → 카탈로그
- 새 프로파일을 프로파일 이력에 먼저 등록하고, 그 프로파일로 대상 채널의 메시지만 다시 계산한다.
- 메시지 본문은 그대로 두고 정렬 시각·정렬 정보(채널 메타데이터,
_align)만 바꾼다. 다른 이유로 Tier-U 인 메시지(미등록, 역전 등)는 그대로 둔다. - 셀 로거와 같은 정렬 엔진으로 계산하고 엔진 버전을 남긴다 (3.7). 원본을 정렬한 엔진이 지금 엔진과 다르면 근거를 바꾸는 재정렬은 하지 않는다.
- 결과는 판본을 올린 새 파일(
_cv2)로 outbox 에 쓰고, 업로더가 수집 경로에 올린다. 원래 파일은 지우지 않는다. - 조회 서비스가 셀 로거 파일과 똑같이 수집 검사(4.3)를 거쳐 등록한다. 조회는 최신 판본을, 스냅샷은 만든 때의 판본을 준다. 재정렬 사실은 카탈로그의 재정렬 알림으로 알린다.
3.7 정렬 엔진과 버전
계산기(3.1)와 재정렬 도구(3.6)의 시각 계산은 정렬 엔진 한 곳(so101_testbed.align_engine)에 있다. 둘이 같은 코드를 쓰므로
같은 근거로 계산하면 결과가 같다.
| 항목 | 내용 |
|---|---|
| 지금 버전 | 1.0.0 (semver) |
| 남기는 곳 | 채널 메타데이터 align_engine_version(그 채널의 모든 기록), _align 레코드, 재정렬본의 fos.correction, 정렬 스트림, 카탈로그 file_channels |
| 버전을 올리는 때 | 같은 입력에 다른 결과를 내는 수정 (계산식, 등급 경계, 반올림). 고정 입력·출력 시험이 깨지면 올려야 한다는 뜻이다 |
| 버전 이전 파일 | 2026-11-18 이전 기록은 계산식이 같아 1.0.0 으로 본다 |
왜 남기나. 같은 구간의 판본이 바뀌었을 때, 그 차이가 근거(지연 모델·시계 측정값)가 바뀌어서인지 엔진을 고쳐서인지 가를 수 있어야 한다.
그래서 근거를 바꾸는 재정렬과 엔진을 바꾸는 재정렬을 한 번에 하지 않는다. 엔진에 결함이 있으면 그 엔진 버전으로 정렬한 구간만
engine_update 사유로 다시 계산한다 (사유는 정의돼 있고, 계산은 아직 없다).
3.8 정렬 스트림 — 모델의 실시간 입력
셀 로거는 메시지를 정렬한 즉시 정렬 결과를 붙여 브로커로 다시 발행한다. 2초 재정렬 버퍼나 파일 닫기(최대 10분)를 기다리지 않는다. 실시간 추론은 이 스트림을 입력으로 쓰고, 그 밖의 추론·학습은 조회 서비스로 받는다. 정렬 전 시각의 브로커 데이터는 모델 입력으로 쓰지 않는다 (학습과 추론이 같은 시간축을 쓰게 하기 위해서다).
| 항목 | 내용 |
|---|---|
| 토픽 | aligned/<채널 ID> — 규약은 토픽 체계를 Fac 규약에 맡겨 아직 없다. 수집기 토픽(testbed/#)과 겹치지 않게 둔 테스트베드 제안값 |
| 내용 | protobuf AlignedRecord: 채널 ID·seq, 정렬 시각, 정렬 여부·등급·불확도, 원래 시각(장치·수집기), 정렬 엔진 버전, 품질, 진단 코드, 수집기 메시지 원본 |
| 짝 맞추기 | 같은 메시지는 채널 ID·seq 로 브로커 구독·조회 결과와 맞춘다. 정렬 시각은 파일의 log_time 과 같은 값 |
| 미추정 | Tier-U 도 발행하되 aligned = false. 소비자가 기본으로 뺀다. 중복(TIM-4091)은 발행하지 않는다 |
| 전달 | QoS 0. 실시간 입력이라 늦은 재전송보다 최신값이 중요하다. 빠짐없는 기록은 파일·조회가 맡는다 |
| 지연 | 규약 제안 목표: 장치 → 발행 p95 100 ms. 셀 로거가 10초마다 수집기 시각 → 발행 지연 p95 를 로그에 남긴다 |
정렬 결과는 발행 시점의 근거로 계산하므로, 나중에 시계 튐 근거가 도착하거나 재정렬되면 조회 결과와 다를 수 있다. 차이는 등급의 불확도 안에 있고, 정렬 시각을 고정해야 하는 판단은 조회로 한다.
4. 저장 — MCAP 와 S3
4.1 MCAP 파일
| 항목 | 내용 |
|---|---|
| 메시지 시각 | log_time = 정렬 시각, publish_time = 셀 로거 수신 시각 |
| 정렬 정보 | 채널마다 <채널>/_align 채널: 메시지별 seq, 불확도, 정렬 방식, 등급, 정렬 여부, 진단 코드 (TS-06). 채널 기본값과 같으면 생략 |
| 채널 메타데이터 | 판본, 프로파일 버전, 정렬 방식, 기본 등급·불확도, 시간 매핑, 정렬 엔진 버전 |
| 첨부 | 그 파일에 적용된 채널 프로파일 |
| 묶음 | arm(관절 4채널), cam(카메라 2채널), context(에피소드 이벤트), sync(시계 근거·프로파일 변경·진단 요약) |
| 파일 단위 | UTC 10분 경계, 30초 무입력, 2 GB, 종료 시 닫음. 닫힌 뒤에는 바꾸지 않는다 |
| manifest | 파일마다 JSON: 크기, SHA-256, 구간, 채널별 메시지 수·시각 범위, 판본, 닫힌 이유 |
4.2 S3 키 구조
mcap/site=<현장>/area=<영역>/line=<라인>/cell=<셀>/date=<UTC 날짜>/<시작>-<끝>_<묶음>_cv<판본>.mcap (+ .json manifest)
mcap/site=<현장>/area=<영역>/_sync/… 시계 근거, 적용 중인 채널 프로파일 사본
inbox/mcap/… 수집 경로 (업로더가 올림, 조회 서비스가 검사 뒤 옮기고 지움)
quarantine/mcap/… 검사에 실패한 파일 (버리지 않음)
ingest/results/mcap/….json 수집 결과 (통과·격리, 사유) → 업로더가 읽는다
mcap/ 에는 조회 서비스가 검사를 통과시킨 파일만 들어간다. 카탈로그의 채널·구간 색인은 셀 로거 manifest 가 아니라 MCAP 에서 직접 뽑는다.
데이터 양은 관절 4채널 합쳐 1분에 약 1 MB, 카메라 2대 1분에 약 120 MB.
4.3 수집 — 조회 서비스가 검사·색인·격리
셀 로거는 닫힌 파일을 수집 경로(inbox/)에 올리기만 한다. 저장소(mcap/)와 카탈로그에는 쓰지 않는다.
조회 서비스가 30초마다 수집 경로를 처리하면서 파일 단위 검사를 하고, 통과한 파일만 저장소로 옮겨 카탈로그에 등록한다.
메시지 단위 시각 검사(3.5)는 셀 로거가, 파일 단위 검사는 조회 서비스가 맡는다.
| 검사 | 보는 것 |
|---|---|
| 전송 | 받은 파일의 SHA-256·크기가 셀 로거 manifest 와 같은가. 같은 경로에 다른 내용이 이미 있지 않은가 (닫힌 파일은 바뀌지 않는다) |
| 형식 | MCAP 를 끝까지 읽을 수 있는가 (청크 CRC), 요약 정보가 있는가 (정상 종료), 요약의 채널별 개수가 실제와 같은가 |
| 필수 메타데이터 | 기록 정보(현장·영역·라인·셀·묶음·판본)가 manifest·저장 경로와 맞는가. 데이터 채널마다 시간 매핑·판본·정렬 엔진 버전이 있는가 |
_align · _sync |
채널 기본 정렬 정보가 없는 채널은 메시지마다 _align 이 있는가. 동기 근거 묶음에는 _sync 채널만 있는가 |
| 재정렬본 | 대체 대상이 파일 안 기록과 manifest 에서 같은가 |
| 색인 | 채널별 구간·개수를 파일에서 직접 뽑는다. 셀 로거 manifest 의 색인과 다르면 셀 로거 결함으로 본다 |
통과 → mcap/<경로> + 조회 서비스가 쓴 manifest → 카탈로그
실패 → quarantine/<경로> (버리지 않는다)
결과 → ingest/results/<경로>.json (통과·격리, 사유 코드) → 업로더가 읽어 로컬 파일을 uploaded/ 또는 rejected/ 로
- 격리된 파일은 원인을 고친 뒤 수집 경로에 다시 올리면 다시 검사한다.
- 규약에 파일 단위 사유 코드가 없어 테스트베드가 19개를 정했다 (
checksum_mismatch,channel_metadata,align_missing,index_mismatch등). - 카탈로그는 수집 검사를 거쳐 들어온 파일을 표시해 둔다. 2026-11-18 이전 방식(셀 로거 manifest 를 그대로 적재)으로 들어온 파일과 구분된다.
5. 조회 서비스 — 서버 (AWS)
5.1 구성
조회 서비스는 하나의 Python 프로세스(FastAPI)다. 아래 모듈이 그 안에서 함께 돈다. 카탈로그 동기화와 내보내기는 별도 스레드로 돌고, 나머지는 요청마다 실행된다. 카탈로그 DB(PostgreSQL)만 별도 프로세스다.
| 모듈 | 하는 일 |
|---|---|
| API · 인증 | IF-03 엔드포인트. 인증 어댑터가 토큰에서 신원·현장·권한을 꺼내고(권한은 운영 커널이 정함, 지금은 고정 토큰 + 정책 파일), 모든 API 가 한 판정 함수(데이터셋 × 목적 → 보안 등급 → 위임 범위 → 현장 밖 내보내기)를 거친다. 보안 등급, 요청마다 감사 기록 |
| 수집 · 카탈로그 동기화 (스레드) | 30초마다 수집 경로 처리: 전송 해시·MCAP 형식·필수 메타데이터·_align·_sync 검사, MCAP 에서 색인을 뽑아 등록, 실패는 격리하고 사유 회신. 저장소에 있는 manifest·프로파일 사본 적재(카탈로그 재구성용)는 증분(최근 2일 폴더)과 1시간마다 전체 |
| 저장소 캐시 | 조회에 필요한 MCAP 을 S3 에서 받아 SHA-256 확인 후 보관 (같은 파일을 다시 받지 않는다) |
| 조회 엔진 | 판본 선택, 조회 원칙(5.2) 적용, 누락 구간·품질 요약, json·arrow 응답, 서명된 페이지 토큰으로 분할 전송 |
| 이벤트 · 연결키 | 작업자 입력을 에피소드 구간으로 묶고, 데이터가 어느 에피소드에 속하는지 불확도를 반영해 판정 (inside / ambiguous) |
| 스냅샷 | 구간·채널의 당시 판본 파일 목록을 고정. 같은 ID 는 언제 읽어도 같은 데이터. 학습 모델 참조 기록 |
| 내보내기 작업 (스레드 풀) | 비동기 작업. Parquet(학습용, 스냅샷 필수), MCAP(여러 원본을 한 파일로, Foxglove 재생) |
| 문서 · SDK 배포 | 이 페이지, SDK 매뉴얼, API 명세, 대화형 API, SDK 패키지 |
| 데이터 사전 매핑 | 채널·규약 필드를 TTA 데이터 사전 항목에 잇는 매핑의 등록·조회·사용 중지(5.5). 카탈로그의 semantic_id 를 채운다. 사전 확인은 어댑터(지금은 연동 없음) |
| PostgreSQL 카탈로그 (별도 프로세스) | 파일, 채널, 판본 대체 관계, 프로파일 이력, 데이터셋, 스냅샷, 내보내기, 수집 기록, 사전 매핑, 접근 기록. 권한은 DB 가 아니라 토큰(정책 파일)에 있다 |
5.2 조회 원칙
| 원칙 | 구현 |
|---|---|
| 시간축은 정렬 시각 하나 | 구간 [start, end)·정렬·채널 간 비교 모두 정렬 시각 기준. 원래 시각은 요청 시 참고 필드로만 |
| 최신 판본 | 재정렬본이 있으면 그 판본, 대체된 쌍은 제외. 분할 전송 중에도 첫 조각과 같은 판본 유지 |
| 미추정 제외 | Tier-U 는 기본 제외, include_unaligned 로 포함. min_tier 로 등급 하한 |
| 만들지 않는다 | 보간·추정 없음. 대신 누락 구간(gaps), 누락 비율, 등급 분포, 불확도, 제외 수를 함께 준다 |
| 한도 | 값 조회 1시간, 이벤트 31일, 내보내기 제한 없음 |
5.3 API
| 기능 | API |
|---|---|
| 카탈로그 (데이터셋·채널·데이터 기간·지연 모델·판본·재정렬 알림) | GET /v1/datasets, GET /v1/datasets/{id} |
| 구간 조회 (시계열·영상·이벤트 레코드) | POST /v1/query |
| 이벤트 (에피소드 구간·점 이벤트) | POST /v1/events |
| 최신값 | GET /v1/latest |
| 영상 본문 | GET /v1/content |
| 스냅샷 | POST /v1/snapshots, GET /v1/snapshots/{id}, GET /v1/datasets/{id}/snapshots, POST /v1/snapshots/{id}/references |
| 내보내기 | POST /v1/exports, GET /v1/exports/{id}, GET /v1/exports/{id}/files/{name} |
| 데이터 사전 매핑 (채널·필드 ↔ TTA 사전 항목) | POST /v1/dictionary/mappings, GET /v1/dictionary/mappings, GET /v1/dictionary/mappings/{id}, POST /v1/dictionary/mappings/{id}/deprecate |
파이썬 SDK databahn 은 요청을 만들고, 분할 전송을 이어 받고, 일시 오류를 다시 시도하고, 결과를 numpy 배열로 바꾼다.
조회 원칙은 서버가 적용하므로 SDK 를 쓰든 API 를 직접 부르든 결과가 같다. 사용법은 SDK 매뉴얼, 필드는 API 명세.
5.4 인증·권한·접근 기록 — 운영 커널과의 경계
권한을 정하는 쪽은 전북대 운영 커널(FacOS, 정책 결정자 PDP)이고, 조회 서비스는 토큰에 담긴 권한대로 집행한다(정책 집행자 PEP). 데이터는 커널을 지나가지 않고, 조회 서비스는 요청마다 커널에 묻지 않는다. 커널과 맞닿는 곳은 토큰(인증 어댑터)과 감사 이벤트 두 곳뿐이다.
소비자 ── 토큰 요청 ──▶ 운영 커널 (신원·권한 정책) ※ 합의 전: 관리자가 등록한 고정 토큰 + 정책 파일
소비자 ── 요청 + 토큰 ──▶ 조회 서비스
인증 어댑터: 토큰 → 신원·현장·권한·내보내기 승인·위임·만료
판정 (한 곳): 데이터셋 × 목적 → 보안 등급 → 위임 범위 → 현장 밖 내보내기
조회 원칙 적용 → 응답
접근 기록 (허가·거부 모두) ─ ─ 감사 요약 이벤트 ─ ─▶ 운영 커널 (예정)
| 구성 | 구현 |
|---|---|
| 인증 어댑터 | 토큰에서 신원(sub), 현장(site_id), 권한(grants: 데이터셋 × 목적, 위임이면 구간), 현장 밖 내보내기 승인(export_scope), 원 요청자(act), 요청 ID(trace_id), 만료(exp)를 꺼낸다. 지금은 고정 토큰 → 정책 파일(tokens.json, 토큰은 해시만) 매핑. FacOS 토큰이 합의되면 어댑터만 바꾼다 |
| 판정 (한 곳) | 모든 API 가 같은 함수 하나를 거친다. ① 데이터셋 × 목적 권한(없으면 DAT-4031, 데이터셋이 있는지도 알리지 않음) ② 보안 등급: restricted 는 토큰 현장 = 데이터셋 현장(DAT-4032) ③ 위임 토큰이면 요청 구간이 위임 범위 안 ④ 내보내기가 현장 밖이면 internal 은 승인 필요, restricted 는 불가. 내보낸 파일을 받을 때도 다시 판정하고, 나중에 도는 내보내기 작업은 요청자 신원으로 다시 판정한다 |
| 접근 기록 | 요청마다 한 행 (IF-03 Table 25 + 현장, 원 요청자, 판정 결과 allow·deny·error). 거부·형식 오류도 허가와 같은 동작 이름·대상·구간으로 남는다 |
| 감사 요약 이벤트 | 커널로 보내는 요약 이벤트(가칭 audit.data_access) — 형식·토픽 합의 전이라 아직 없다 |
합의를 기다리는 것 (그때까지 위 기본값으로 동작): 토큰에 권한을 담는 방식(K1), 정책 관리 위치(K2), 감사 이벤트 형식(K3), 위임 토큰(K5), 보안 등급 거부 코드(DAT-4031 로 통일할지), 서비스 간 인증 방식, 접근 기록 보존 기간.
데이터 접근 권한(grants)과 별개로 관리 권한(roles)이 있다. 지금은 dict_admin(사전 매핑 등록·사용 중지, 5.5) 하나이며,
정책 파일에서 계정마다 준다 (fabric.admin role <계정> dict_admin, 서버는 deploy_ec2.sh role).
5.5 데이터 사전 매핑 — 채널의 뜻을 표준 항목으로
과제 데이터 모델은 AAS(자산관리셸)를 틀로 하고, 데이터 항목의 뜻은 TTA 가 관리하는 데이터 사전의 항목 ID(semantic_id)로 나타낸다.
측정값은 AAS 에 복사하지 않고 링크로 IF-03 을 가리키므로, "이 채널은 사전의 어느 항목인가"를 잇는 일을 IF-03 이 맡는다.
사전 자체(항목의 이름·정의·단위)는 복제하지 않고 매핑만 관리한다.
TTA 데이터 사전 (외부, 항목 ID·정의) ※ 지금은 연동 없음 — 확인 어댑터 none
▲ 항목이 있나 확인 (어댑터: none | id_list | http 예정)
관리자(dict_admin) ── 매핑 등록·교체·사용 중지 ──▶ 사전 매핑 (dict_mappings)
│ 채널·tag·규약 필드 → 항목 ID·버전
소비자 ── 대상 기준 / 사전 기준 조회 ───────────────────┤
카탈로그 데이터셋 상세 ◀── semantic_id ──────────────────┤
IF-20 모델 입출력 semantic_id ◀── 같은 매핑 (같은 항목을 가진 설비에 모델을 붙일 수 있나) ┘
| 항목 | 내용 |
|---|---|
| 대상 | 채널, tag(채널 안 값 하나, <채널>#<tag> — 관절 6개가 한 채널에 있어 테스트베드가 더함), 규약 필드(ts_aligned 등), 데이터셋 정의 필드 |
| 레코드 | 매핑 ID, 대상, 사전 항목 ID·버전, 상태(활성·사용 중지), 등록 주체, 적용 시작. 테스트베드가 더한 것: 사전 확인 결과, 대체한 매핑, 사용 중지 시각·주체 |
| 규칙 | 대상마다 활성 매핑은 하나. 바꿀 때는 지금 매핑 ID 를 replaces 로 주고 새 버전을 등록한다 (이전 것은 사용 중지, 지우지 않음) |
| 권한 | 등록·사용 중지는 dict_admin, 조회는 인증된 누구나. 단 채널·tag 매핑은 그 데이터셋 권한이 있어야 보인다 (권한 없는 데이터는 있는지도 알리지 않는다) |
| 사전 확인 | TTA 연동 전에는 확인하지 않고 unverified 로 등록한다. TTA 가 항목 ID 목록(파일)이나 조회 API 를 주면 어댑터만 바꾸고, 쌓인 매핑을 다시 확인한다 (사전에 없으면 지우지 않고 표시) |
6. 검증
- 자동 테스트 214개: 시각 계산(같은 프로세스·사이드카 결과 일치, 계산기 중단 시 미정렬 기록과 재연결), 시계 튐 감지(측정 잡음과 진짜 튐 구별), 정렬 엔진 고정값, 정렬 스트림, 사전 매핑(교체·권한·보이는 범위·사전 확인), 창 모듈(학습·추론 텐서 일치), 기준 모델(ONNX 그래프와 numpy 기준 구현 일치, 빈 칸 처리), 위임(원 요청자 권한 판정·접근 기록), IF-20 게이트웨이(등록 규칙·서명 변조 거부·배포 교체·준비 실패 시 이전 유지·롤백·값·참조 전달 추론, SDK
Models, 매핑 사용 중지 알림 semantic_drift, 시험 현장 분리), 학습 Job 정의(비밀은 Secret 참조로만, 클러스터 권한 없음), 시계 상태, 재정렬(엔진 혼합 거부), 업로더(조건부 쓰기·해시·수집 결과), 수집 검사(통과·격리 사유별 양성·음성 대조), 카탈로그 동기화, 조회 원칙, 권한 판정(현장·위임·현장 밖 내보내기·만료)과 접근 기록, 스냅샷, 내보내기, 연결키, arrow, SDK. - 실제 장치 전체 경로 점검
scripts/check_pipeline.py(로컬에서 실행): 각 프로세스 로그 → MCAP → 수집 결과·저장소(크기·해시) → 서버 카탈로그 → 조회·이벤트·연결키·최신값까지 단계별로 확인한다. 실제 녹화로 17개 항목 모두 정상 (2026-11-16, 수집 경로 도입 전). EKS 이전 뒤 EC2 를 멈추고 EKS 단독으로 18개 항목 모두 정상 — 에피소드·연결키 포함 (2026-11-18). - IF-20 경로: 기준 모델(관절 추종 오차 이상 점수)을 스냅샷 → 학습용 내보내기 → 창 모듈 → ONNX → MLflow run → IF-20 등록(서명) → IF-20 배포(Triton) → 추론까지 돌렸다. P4 대역 종단 시험(배포 → 값·참조 추론 → 교체 → 롤백)이 통과했고, 추론 응답의 trace_id 하나로 IF-20 감사 → 학습 이력 → IF-03 접근 기록(서빙 계정이 원 요청자 대신 읽음)까지 이어진다 (2026-11-18, docs/deploy-eks.md).
- 학습은 클러스터의 학습 Job(
python -m if20.train)이 하고, 노트북은 Job 만 만든다. MLflow 는 인증 모드라 쓰기는 학습 Job(run)과 IF-20(모델 버전·별칭)만 할 수 있다 — 노트북이 MLflow 에 직접 모델을 올려 IF-20 의 등록 규칙(학습 이력·서명)을 건너뛰는 길을 막았다 (2026-11-19). - 지연 모델은 실측으로 정했다: 관절은 왕복 시간, 카메라는 영상·엔코더 상호상관 (프로파일에 측정 시각·방법 기록).
- SDK 매뉴얼의 예제는 모두 이 서버에서 실행해 결과를 확인했다.
7. 한계와 다음 단계
- 시각 등급은 Tier-3 가 상한이다 (3.5). Tier-2 는 PTP·장치 타임스탬프가 필요하다.
- 장치 USB 가 한꺼번에 끊기면 수집기가 멈춘다. 전원 있는 허브와 수집기 자동 재연결이 필요하다.
- 조회는 실시간이 아니다. 파일이 닫혀야(최대 10분) 조회된다. 실시간 입력은 정렬 스트림(3.8)이 맡는다.
- 정렬 스트림 토픽 체계와 수집 실패 사유 코드는 규약에 없어 테스트베드가 정했다. 규약이 정해지면 맞춘다.
engine_update재정렬은 사유만 있고 계산이 없다 (3.7). 수집 격리 사유는 업로더 로그와rejected/에만 남는다 (화면·알림 없음).- 계산기를 다시 시작하면 채널별
seq기록과 시계 상태가 처음부터 다시 쌓인다 (다음 NTP 측정까지 설정값 사용). - 보존 기간 정리(오래된 데이터 삭제)가 아직 없다. 카탈로그 DB 백업은 EKS 에서 매일 S3 로 (첫 실행 확인 전).
- 수집·카탈로그 동기화는 폴링이다. 셀이 늘면 S3 이벤트 알림 + 큐로 바꾼다.
- 데이터 사전(TTA)과 연동이 없다. 사전 매핑은 항목이 실제로 있는지 확인하지 않고
unverified로 등록한다 (연동 뒤 다시 확인, 5.5). TTA 의 제공 방식·항목 ID 형식·버전 체계를 받아야 한다. - 업로더는 아직 개인 계정으로 돈다. 수집 경로 쓰기·결과 읽기만 가진 전용 계정으로 바꿔야 한다.
- 운영 커널로 보내는 감사 요약 이벤트가 아직 없다 (5.4). 권한은 고정 토큰과 정책 파일이 대신한다.