databahn SDK 매뉴얼
databahn 은 IF-03 데이터 소비 규약의 조회 서비스를 파이썬에서 쓰는 클라이언트다.
이 문서만 보고 저장된 모든 데이터(관절 시계열, 카메라 영상, 작업 이벤트)를 찾고, 꺼내고, 학습용으로 내보낼 수 있도록 썼다.
- databahn SDK 매뉴얼
- 0. 5분 만에 시작하기 — Foxglove 로 재생하기
- 1. 설치
- 2. 연결
- 3. 먼저 알아 둘 개념
- 4. 데이터 찾기 — 카탈로그
- 5. 구간 조회 — fab.read
- 6. 품질 정보 — 누락, 등급, 판본
- 7. 이벤트 — 작업(에피소드)
- 8. 연결키 — 특정 작업의 데이터만
- 9. 영상
- 10. 최신값
- 11. 스냅샷 — 학습 데이터 고정
- 12. 내보내기 — 파일로 받기
- 12-1. 데이터 사전 매핑 — 채널의 뜻을 표준 항목으로
- 12-2. 창 — 모델 입력 텐서 만들기 (databahn.window)
- 12-3. 모델 추론 — databahn.Models (IF-20)
- 13. data_ref — 다른 시스템과 같은 데이터 가리키기
- 14. 오류 처리
- 15. 레시피
- 16. 메서드 요약
- 17. 한도와 성능
0. 5분 만에 시작하기 — Foxglove 로 재생하기
실제로 녹화된 작업 하나(2026-11-16 17:53:39~17:54:09 KST, 30초)를 MCAP 파일로 받아 Foxglove 에서 관절 그래프로 본다.
1) 설치와 키
pip install "https://if03.data-bahn.com/sdk/databahn-0.4.1-py3-none-any.whl"
export FABRIC_URL=https://if03.data-bahn.com
export FABRIC_API_KEY_FILE=~/.config/databahn/key # 관리자에게 받은 접근 토큰(API 키) 파일
2) MCAP 로 내보내기
from databahn import Fabric
fab = Fabric() # 위 환경 변수를 읽는다
print(fab.datasets()) # 내가 볼 수 있는 데이터셋
C = "testbed/so101/cell-01/"
job = fab.export(
"mcap",
dataset_id="plab-testbed-cell01",
start="2026-11-16T17:53:39+09:00", # 실제 녹화된 작업 구간 (에피소드 ep-20261116T085339Z)
end="2026-11-16T17:54:09+09:00",
channels=[C + "leader-arm/joint_state", # 리더암 관절 (사람이 움직인 팔)
C + "follower-arm/joint_state", # 팔로우암 관절 (따라 움직인 팔)
C + "follower-arm/joint_command"], # 팔로우암에 보낸 명령
purpose="display",
)
print("내보내기 작업:", job.export_id)
paths = job.wait().download("foxglove") # 서버가 파일을 다 만들면 내려받는다 (SHA-256 확인)
print(paths[0], paths[0].stat().st_size // 1024, "KB")
# foxglove/exp-20261116-xxxxxxxx.mcap 459 KB (관절 3채널 × 1,799 메시지)
여러 원본 파일에 걸친 구간이어도 파일 하나로 받는다. 메시지 시각이 정렬 시각(실제 측정 순간 추정)이라 채널들이 맞춰진 채로 재생된다.
3) Foxglove 에서 열기
- Foxglove 에서 Open local file 로 받은
.mcap을 연다. - Plot 패널을 추가하고 + Add series 로 아래 경로를 넣는다 (토픽 이름 앞부분만 쳐도 자동완성된다).
"testbed/so101/cell-01/leader-arm/joint_state".joints[:]{name=="gripper"}.position
"testbed/so101/cell-01/follower-arm/joint_state".joints[:]{name=="gripper"}.position
리더와 팔로우를 한 그래프에 겹치면 팔로우암이 얼마나 늦게·정확하게 따라가는지 보인다. 다른 관절은 gripper 자리에
shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll 을 넣는다. 관절마다 Plot 패널을 하나씩 두면 보기 좋다.
| 보고 싶은 것 | 경로 ("testbed/so101/cell-01/…" 토픽 뒤) |
|---|---|
| 관절 위치 | leader-arm/joint_state / follower-arm/joint_state → .joints[:]{name=="<관절>"}.position |
| 팔로우암에 보낸 명령 | follower-arm/joint_command → .targets[:]{name=="<관절>"}.sent_position (요청값 requested_position) |
| 시각 불확도·등급 | follower-arm/joint_state/_align → .uncertainty_ns, .tier (메시지마다 하나) |
시간축은 기본값(Receive time)을 그대로 둔다. 이 파일에서는 그것이 정렬 시각이다.
카메라도 보려면 channels 에 C + "wrist-cam/image", C + "top-cam/image" 를 더한다. 카메라 두 대면 30초에 약 60 MB 다.
영상은 테스트베드 전용 메시지 형식이라 Foxglove 에 이미지 변환 확장을 한 번 설치해야 한다:
SDK 내려받기 에서 .foxe 파일을 받아 Foxglove 창에 끌어다 놓고, Image 패널에서 카메라 토픽을 고른다.
numpy 로 바로 받고 싶으면 파일 없이 조회한다 (5장).
b = fab.read(dataset_id="plab-testbed-cell01", channels=[C + "follower-arm/joint_state"],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:50+09:00", purpose="analysis")
grip = b.select(C + "follower-arm/joint_state", "gripper/position")
print(len(grip.values), grip.unit) # 600 range_0_100 (60 Hz × 10초)
여기까지 되면 나머지는 필요한 장만 골라 읽으면 된다.
| 하고 싶은 것 | 볼 곳 |
|---|---|
| 어떤 데이터가 언제 있는지 | 4장 카탈로그 |
| 관절 값을 numpy·pandas 로 | 5장 구간 조회 |
| 데이터가 빠진 곳·신뢰도 | 6장 품질 정보 |
| 작업(에피소드) 목록, 성공·실패 | 7장 이벤트 |
| 특정 작업의 데이터만 | 8장 연결키 |
| 카메라 이미지 | 9장 영상 |
| 학습 데이터셋 고정·Parquet 파일 | 11장 스냅샷, 12장 내보내기 |
| 긴 구간·카메라 포함 MCAP | 12장 MCAP 내보내기 |
| 바로 쓸 수 있는 코드 | 15장 레시피 |
1. 설치
파이썬 3.10 이상. 의존 패키지(httpx, numpy, pyarrow)는 함께 설치된다.
pip install "https://if03.data-bahn.com/sdk/databahn-0.4.1-py3-none-any.whl"
python -c "import databahn; print(databahn.__version__)" # 0.4.1
지금 판은 0.4.1 (2026-11-19: 모델 추론·배포 클라이언트 Models, semantic_drift 알림, get_mapping. 0.3: 데이터 사전 매핑, semantic_id 해석, 창 모듈). 판 이름은 서버 /sdk/ 목록에서 확인한다.
예전 판이 깔려 있으면 위 명령이 새 판으로 바꿔 설치한다.
서버가 자체 서명 인증서를 쓰면(주소가 IP 이고 브라우저가 경고를 띄우는 경우) CA 인증서로 wheel 을 받은 뒤 파일로 설치한다.
pip install --cert 는 신뢰 목록을 통째로 바꿔서 PyPI 에서 의존 패키지를 받지 못하므로 쓰지 않는다.
curl -kO https://if03.data-bahn.com/sdk/ca.crt
curl --cacert ca.crt -O "https://if03.data-bahn.com/sdk/databahn-0.4.1-py3-none-any.whl"
pip install ./databahn-0.4.1-py3-none-any.whl
export FABRIC_CA_BUNDLE=$PWD/ca.crt
이 문서의 예제 중 일부는 pandas, matplotlib, Pillow 를 쓴다. 필요할 때만 설치한다.
pip install pandas matplotlib pillow
2. 연결
from databahn import Fabric
fab = Fabric("https://if03.data-bahn.com", api_key="fk_...") # 직접 넘기기
fab = Fabric() # 환경 변수에서 읽기 (권장)
| 인자 | 기본값 | 설명 |
|---|---|---|
url |
환경 변수 FABRIC_URL, 없으면 http://127.0.0.1:8030 |
조회 서버 주소 |
api_key |
FABRIC_API_KEY, 없으면 FABRIC_API_KEY_FILE 파일 내용 |
접근 토큰(API 키). 관리자가 발급한다 (2.1) |
verify |
FABRIC_CA_BUNDLE, 없으면 True |
TLS 인증서 확인. 자체 서명 서버면 CA 파일 경로 |
timeout |
120 |
요청 하나의 시간 한도(초). 큰 구간·느린 네트워크면 늘린다 |
retries |
3 |
서버 일시 장애(DAT-5031)·연결 오류 때 자동으로 다시 시도하는 횟수 |
토큰은 코드에 적지 않는다. 파일로 두고 경로만 환경 변수로 넘기면 코드가 git 에 올라가도 토큰이 새지 않는다.
mkdir -p ~/.config/databahn && chmod 700 ~/.config/databahn
cp 받은키파일 ~/.config/databahn/key && chmod 600 ~/.config/databahn/key
export FABRIC_URL=https://if03.data-bahn.com
export FABRIC_API_KEY_FILE=~/.config/databahn/key
토큰이 없으면 Fabric() 이 ValueError 를 낸다. 토큰이 틀리거나 만료됐으면 첫 요청에서 FabricError DAT-4031.
with 로 쓰면 끝날 때 연결을 닫는다(스크립트에서는 생략해도 된다).
with Fabric() as f:
print(len(f.datasets()))
2.1 접근 토큰과 권한
SDK 인자 이름은 api_key 지만, 서버 쪽에서는 접근 토큰이다. 서버는 토큰 하나로 "누가, 어느 현장에서, 무엇을 할 수 있는지"를 안다.
권한을 정하는 것은 운영 커널(전북대)이고, 조회 서비스는 토큰에 담긴 권한대로 집행만 한다. 지금은 커널과의 합의 전이라 관리자가
등록한 고정 토큰과 정책 파일이 이 역할을 대신한다. 토큰 문자열 자체는 서버에 저장되지 않는다 (해시만).
토큰에 담긴 것:
| 항목 | 뜻 | 영향 |
|---|---|---|
신원 (sub) |
사용자 또는 서비스 계정 | 접근 기록, 내보내기 작업의 주인 |
현장 (site_id) |
소속 현장 (예: partridge-lab) |
restricted 데이터는 같은 현장만 볼 수 있다. 다른 현장에서 internal 데이터를 내보내려면 승인이 필요하다 |
권한 (grants) |
데이터셋 × 목적 목록 | 허용되지 않은 데이터셋·목적은 DAT-4031. 내 권한은 fab.datasets() 의 allowed_purposes 로 본다 |
내보내기 승인 (export_scope) |
on_site 또는 off_site_approved |
현장 밖에서 internal 데이터를 내보낼 때만 off_site_approved 가 필요하다 |
위임 (act, trace_id) |
다른 요청을 대신 처리하는 토큰이면 원 요청자와 그 요청 ID | 정해진 구간·목적만 읽을 수 있다. 응답의 trace_id 가 그 요청 ID 가 된다 |
만료 (exp) |
지나면 쓸 수 없다 | DAT-4031 "토큰 만료" |
알아 둘 점:
- 권한 판정은 모든 API 가 같다. 목록·상세·조회·스냅샷·내보내기 모두 같은 순서로 확인한다: 데이터셋 × 목적 → 보안 등급 → (위임이면) 구간 → (내보내기면) 현장 밖 승인.
- 권한이 없는 데이터셋은 있는지도 알 수 없다. 이름이 틀려도, 권한이 없어도 똑같이 DAT-4031 이다.
- 내보낸 파일을 받을 때도 다시 확인한다. 그사이 권한이 빠지면 이미 만든 파일도 받을 수 없다.
- 토큰을 새로 받으면 예전 토큰은 바로 쓸 수 없다. 권한은 새 토큰으로 이어진다.
- 모든 요청(거부 포함)은 서버의 접근 기록에 신원·현장·목적·판정 결과와 함께 남는다.
3. 먼저 알아 둘 개념
3.1 데이터의 구조
데이터셋 plab-testbed-cell01 ← 권한·조회 단위 (테스트베드는 셀 하나)
└ 채널 testbed/so101/cell-01/follower-arm/joint_state ← 센서 하나의 데이터 흐름
└ tag elbow_flex/position, gripper/position, … ← 채널 안의 항목 (관절별 값)
└ 레코드: 정렬 시각 ts_ns + 값 value + 단위 unit + 등급 tier + 불확도 uncertainty_ns …
| 개념 | 뜻 |
|---|---|
| 데이터셋 | 이름 붙인 채널 묶음. 권한을 주고 조회를 요청하는 단위. 이름에 기간을 넣지 않는다 — 데이터가 쌓여도 같은 이름 |
| 채널 | 데이터 흐름 하나. <구역>/<라인>/<셀>/<장치>/<신호> |
| tag | 시계열 채널 안의 항목. 한 메시지에 여러 관절 값이 함께 들어 있고, 관절마다 tag 하나 |
| 레코드 | 조회 결과의 한 줄. 시계열은 (메시지 × tag) 마다, 영상은 프레임마다, 이벤트는 사건마다 하나 |
3.2 테스트베드 채널 (SO-101 셀 1)
채널 이름은 모두 testbed/so101/cell-01/ 로 시작한다. 아래 표는 그 뒤만 적었다.
| 채널 | 종류 | 주기 | tag (관절마다) | 단위 |
|---|---|---|---|---|
leader-arm/joint_state |
시계열 | 60 Hz | <관절>/position |
deg (그리퍼는 range_0_100) |
follower-arm/joint_state |
시계열 | 60 Hz | <관절>/position |
〃 |
follower-arm/joint_command |
시계열 | 60 Hz | <관절>/requested_position, <관절>/sent_position |
〃 |
follower-arm/joint_health |
시계열 | 1 Hz | <관절>/temperature, <관절>/voltage |
degC, V |
wrist-cam/image |
영상 | 30 fps | — (JPEG 640×480) | |
top-cam/image |
영상 | 30 fps | — (JPEG 640×480) | |
operator-console/episode |
이벤트 | 작업자 입력 | — (에피소드 시작·끝·폐기·표시) |
관절 6개: shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper.
그리퍼는 0(닫힘)~100(열림), 나머지는 각도.
requested_position: 리더암을 따라가라고 요청한 값sent_position: 안전 제한(속도·범위)을 거쳐 실제로 모터에 보낸 값
3.3 시각과 신뢰도
| 개념 | 뜻 |
|---|---|
정렬 시각 ts_ns |
실제 사건 시각의 추정값 (관절은 측정 순간, 카메라는 노출 중앙). UTC 기준 int64 나노초. 구간·순서·채널 간 비교의 기준은 이것뿐 |
불확도 uncertainty_ns |
정렬 시각이 실제와 다를 수 있는 최대 폭. 장치 지연 폭 + 컴퓨터 시계 오차. 예: 22 ms → 실제 시각은 ±22 ms 안 |
등급 tier |
불확도로 정하는 신뢰 수준. Tier-1(≤1 µs) · Tier-2(≤1 ms) · Tier-3(≤100 ms) · Tier-4(그보다 큼) · Tier-U(추정 못 함) |
| 미추정 Tier-U | 시각을 추정하지 못한 기록. 기본 조회에서 빠진다. 작업자가 콘솔로 입력한 에피소드 이벤트가 여기 속한다 → include_unaligned=True |
판본 correction_version |
같은 데이터의 기록 버전. 처음 기록은 1, 시각을 다시 계산한 재정렬본은 2 이상. 조회는 늘 최신 판본을 준다 |
품질 quality |
기록 당시 컴퓨터 시계 동기 상태. GOOD(동기됨) / UNCERTAIN(동기 근거가 오래됨·없음) |
테스트베드 관절·카메라는 Tier-3 이다(불확도 10~50 ms). 채널 간 비교는 이 폭 안에서만 의미가 있다.
3.4 시각 적는 법과 구간 규칙
시각은 세 가지 중 하나로 적는다.
from datetime import datetime
from zoneinfo import ZoneInfo
"2026-11-16T17:53:40+09:00" # ISO 8601 문자열 (시간대 필수: +09:00, Z)
1794819220000000000 # int 나노초 (UTC)
datetime(2026, 11, 16, 17, 53, 40, tzinfo=ZoneInfo("Asia/Seoul")) # datetime (시간대 필수)
- 시간대가 없는 시각(
"2026-11-16 17:53",tzinfo없는datetime)은 받지 않는다. 어느 나라 시각인지 모호하기 때문이다. - 구간은 시작 포함, 끝 제외
[start, end). 10초씩 이어 붙여도 겹치거나 빠지는 레코드가 없다. - 결과의 시각은 늘 UTC 나노초다. 사람이 읽을 시각으로 바꾸려면:
from datetime import datetime
from zoneinfo import ZoneInfo
def kst(ns):
return datetime.fromtimestamp(ns / 1e9, ZoneInfo("Asia/Seoul")).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
print(kst(1794819220000756000)) # 2026-11-16 17:53:40.000
3.5 정렬 시각은 어떻게 만들어지나 — 보정 모델 M3
테스트베드의 관절과 카메라는 장치가 자기 시각을 찍어 보내지 않는다. 그래서 수집 컴퓨터가 데이터를 받은 시각에서 장치에서 거기까지 걸리는 지연을 빼서 실제 사건 시각을 추정한다. 이것이 규약(TS 2.5)의 M3 지연 모델이다.
실제 사건 (관절 측정·카메라 노출 중앙)
│ ← 장치 지연: 평균 d, 흔들림 폭 b (채널마다 미리 실측해 프로파일에 적어 둔다)
▼
수집 컴퓨터가 받은 시각 ts_gateway
→ 정렬 시각 ts_ns = ts_gateway − d
→ 불확도 uncertainty_ns = b + 컴퓨터 시계 오차
→ 등급 tier = 불확도로 결정 (≤1 ms Tier-2, ≤100 ms Tier-3, 그 위 Tier-4)
- d (
mean_ns): 장치 지연의 평균. 정렬 시각을 이만큼 앞으로 당긴다. - b (
bound_ns): 지연이 평균에서 벗어날 수 있는 최대 폭. 불확도에 그대로 더한다. - 컴퓨터 시계 오차: 수집 컴퓨터 시계가 표준시(UTC)와 얼마나 다를 수 있는지. 동기 에이전트가 1분마다 NTP 로 재서 기록한다. 시계가 갑자기 튀거나 동기가 끊기면 그 구간은 시각을 믿을 수 없으므로 Tier-U 가 된다.
채널별 모델 (프로파일 0.2.0, 컴퓨터 시계 오차는 측정값에 따라 다르다. 아래는 약 17 ms 일 때):
| 채널 | 시각 기준점 | d (평균 지연) | b (흔들림 폭) | 불확도 = b + 시계 | 등급 | d·b 를 잰 방법 |
|---|---|---|---|---|---|---|
follower-arm/joint_state |
모터 읽기 요청·응답 | 0.6 ms | 5 ms | 약 22 ms | Tier-3 | 요청 직전·응답 직후 시각의 중간을 측정 순간으로, 왕복 시간 실측 |
leader-arm/joint_state |
〃 | 0.6 ms | 6 ms | 약 23 ms | Tier-3 | 〃 |
follower-arm/joint_command |
모터 쓰기 | 0.1 ms | 3 ms | 약 20 ms | Tier-3 | 〃 |
follower-arm/joint_health |
모터 읽기 | 1.1 ms | 4 ms | 약 21 ms | Tier-3 | 〃 |
wrist-cam/image |
프레임 수신, 노출 중앙 기준 | 36 ms | 31 ms | 약 48 ms | Tier-3 | 팔을 움직이며 영상 변화와 엔코더 움직임의 상관이 최대인 지연 |
top-cam/image |
〃 | 40 ms | 35 ms | 약 52 ms | Tier-3 | 〃 |
operator-console/episode |
사람 입력 | — | — | — | Tier-U | 사람 반응 지연은 잴 수 없어 추정하지 않는다 |
왜 Tier-3 인가. Tier-2 가 되려면 불확도가 1 ms 이하여야 한다. 지금은 컴퓨터 시계 오차(Wi-Fi NTP, 10~20 ms)만으로도 넘고, 관절의 흔들림 폭(USB 시리얼 왕복 3~6 ms)도 넘는다. 하드웨어 시각 기록(PTP 등)과 장치 자체 타임스탬프가 있어야 Tier-2 가 된다. 반대로 Tier-3 의 뜻은 "수십 ms 범위 안에서 채널끼리 비교해도 된다"이다. 관절 궤적과 영상 프레임을 맞추는 정도는 충분하다.
모델 값은 데이터셋 상세(4.2)의 채널 정보 latency_model 로 볼 수 있고, 레코드에서 직접 확인할 수도 있다.
F = "testbed/so101/cell-01/follower-arm/joint_state"
W = "testbed/so101/cell-01/wrist-cam/image"
profile = {c["channel_id"]: c for c in fab.dataset("plab-testbed-cell01")["channels"]}
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F, W],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:41+09:00",
purpose="analysis", include_raw_times=True)
for ch in (F, W):
m = profile[ch]["latency_model"]
r = next(x for x in b.records if x["channel_id"] == ch)
d = r["raw_times"]["ts_gateway_ns"] - r["ts_ns"] # 받은 시각 − 정렬 시각 = 당긴 만큼
clock = r["uncertainty_ns"] - m["bound_ns"] # 불확도 − 흔들림 폭 = 그때의 시계 오차
print(f"{ch.split('cell-01/')[1]:24s} {profile[ch]['align_method']} "
f"d={d / 1e6:.1f} ms (프로파일 {m['mean_ns'] / 1e6:.1f}) "
f"불확도 {r['uncertainty_ns'] / 1e6:.0f} ms = b {m['bound_ns'] / 1e6:.0f} + 시계 {clock / 1e6:.0f} → {r['tier']}")
# follower-arm/joint_state M3 d=0.6 ms (프로파일 0.6) 불확도 22 ms = b 5 + 시계 17 → Tier-3
# wrist-cam/image M3 d=36.0 ms (프로파일 36.0) 불확도 48 ms = b 31 + 시계 17 → Tier-3
이 지식으로 할 수 있는 것:
- 두 채널 사건의 선후를 판단할 때: 시각 차가 두 불확도의 합보다 커야 "확실히 먼저"라고 말할 수 있다. 예: 관절(22 ms)과 손목 영상(48 ms)은 70 ms 보다 가까운 사건의 순서를 가릴 수 없다.
- 더 엄격한 기준이 필요할 때:
min_tier는 등급 단위(100 ms)라 거칠다.uncertainty_ns로 직접 거른다(6.3). - 시계 오차가 커진 구간 찾기: 같은 채널인데 불확도가 평소보다 크면 그때 컴퓨터 시계 동기가 나빴던 것이다.
quality가UNCERTAIN이면 동기 근거가 오래된 상태였다.
3.6 목적 purpose
모든 조회에 "무엇에 쓰려는지"를 밝힌다. 돌려받는 데이터는 목적과 상관없이 같다. 서버는 이 값으로 권한을 확인하고 기록(감사 로그)을 남긴다.
| purpose | 쓰는 경우 |
|---|---|
analysis |
분석·탐색·그래프 |
display |
화면 표시·재생 (대시보드, Foxglove) |
training |
모델 학습 데이터 |
evaluation |
모델 평가 |
inference |
운영 중인 모델의 추론 입력 |
audit |
감사·검증 열람 |
권한은 "내 토큰 × 데이터셋 × 목적" 조합으로 주어진다 (2.1). 내 토큰에 허용된 목적은 fab.datasets() 의 allowed_purposes 에 나온다.
스냅샷(11장)은 training, evaluation, audit 에만 만들 수 있다.
4. 데이터 찾기 — 카탈로그
이 장부터의 예제는
fab = Fabric()(2장) 과 시각을 읽기 쉽게 바꾸는kst()(3.4) 가 있다고 보고 쓴다. 예제의 날짜·시각은 테스트베드에 실제로 있는 녹화 구간이다 (에피소드ep-20261116T085339Z, 2026-11-16 17:53:39~17:54:08 KST).
4.1 데이터셋 목록 fab.datasets()
for ds in fab.datasets():
print(ds)
# {'dataset_id': 'plab-testbed-cell01', 'site_id': 'partridge-lab', 'modality': ['timeseries', 'image', 'event'],
# 'channel_count': 7, 'security_level': 'internal', 'allowed_purposes': ['analysis', 'display', 'training']}
권한이 있는 데이터셋만 나온다. 걸러 볼 수도 있다: fab.datasets(site_id="partridge-lab"), fab.datasets(modality="image"), fab.datasets(purpose="training").
| 필드 | 뜻 |
|---|---|
dataset_id |
조회에 쓰는 이름 |
site_id |
현장 |
modality |
들어 있는 데이터 종류 (timeseries, image, event) |
channel_count |
채널 수 |
security_level |
open / internal / restricted (restricted 는 현장 안 소비자만) |
allowed_purposes |
내 키로 쓸 수 있는 목적 |
4.2 데이터셋 상세 fab.dataset(id)
채널마다 주기, 기대 등급, 데이터가 있는 기간, 메시지 수, 판본을 알려 준다. 어느 시각을 조회할지 정할 때 먼저 본다.
detail = fab.dataset("plab-testbed-cell01")
for c in detail["channels"]:
p = c["data_period"]
print(f"{c['channel_id'].split('cell-01/')[1]:28s} {c['sampling_rate_hz'] or '-':>5} Hz "
f"{c['expected_tier']:7s} {kst(p['first_ns']) if p else '-'} ~ {kst(p['last_ns']) if p else '-'} "
f"메시지 {c['message_count']:>7} 판본 {c['correction_versions']}")
| 필드 | 뜻 |
|---|---|
channels[].channel_id |
채널 이름 |
channels[].signal_type |
continuous(연속 측정) / event(사건) |
channels[].sampling_rate_hz |
기대 주기 (이벤트 채널은 None) |
channels[].expected_tier |
이 채널이 정상일 때 나와야 하는 등급 |
channels[].align_method |
정렬 방식. M3(지연 모델) / NONE(추정 안 함, Tier-U) |
channels[].latency_model |
M3 지연 모델 {mean_ns(d), bound_ns(b), measured_at, method} (3.5). 없으면 None |
channels[].time_origin, event_point |
시각 기준점(gateway_poll, receiver, human_entry), 사건 시점(exposure_mid 등) |
channels[].min_detectable_ns |
이보다 짧은 간격의 두 사건은 구별할 수 없다 (보통 샘플 주기) |
channels[].data_period |
{first_ns, last_ns} 저장된 데이터의 처음·마지막 시각 (없으면 None) |
channels[].message_count |
저장된 메시지 수 |
channels[].correction_versions |
있는 판본 목록 (2 이상이 있으면 재정렬된 구간이 있다) |
link_rules |
연결키 규칙 (8장) |
corrections |
재정렬 알림: 언제 어느 채널·구간이 몇 판으로 다시 계산됐는지 (최근 100건) |
data_period 는 전체의 처음과 끝일 뿐, 중간이 비어 있을 수 있다(장치를 켜 둔 시간에만 기록된다).
실제로 녹화된 구간을 찾으려면 에피소드 이벤트(7장)를 보거나, 넓은 구간을 조회해 gaps(6장)를 본다.
5. 구간 조회 — fab.read
5.1 기본
b = fab.read(dataset_id="plab-testbed-cell01",
channels=["testbed/so101/cell-01/follower-arm/joint_state",
"testbed/so101/cell-01/leader-arm/joint_state"],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:00+09:00",
purpose="analysis")
print(b) # Batch(14394 records, 12 series, versions={...})
| 인자 | 기본값 | 설명 |
|---|---|---|
dataset_id |
— | 조회할 데이터셋. snapshot_id 를 주면 생략 |
snapshot_id |
— | 스냅샷으로 조회 (11장). 구간을 생략하면 스냅샷 전체 |
start, end |
— | 구간 [start, end). 한 번에 최대 1시간 (넘으면 DAT-4002 → 5.7 처럼 나눠 받기) |
window |
— | {"start": …, "end": …} 로 구간을 줄 때 (start/end 대신) |
channels |
전부 | 고를 채널 (전체 이름). 관절 하나만 받는 기능은 없다 — 채널로 받고 select 로 고른다 |
purpose |
(필수) | 3.6 |
min_tier |
"Tier-4" |
이보다 낮은 등급 레코드 제외. "Tier-3" 이면 불확도 100 ms 넘는 것은 뺀다 |
include_unaligned |
False |
미추정(Tier-U) 레코드도 포함. 에피소드 이벤트를 같이 받으려면 True |
include_raw_times |
False |
레코드에 원래 시각(raw_times)을 붙인다 (5.8) |
link_keys, link_filter, link_ambiguous |
— | 연결키 (8장) |
format |
"arrow" |
"arrow"(압축 열 형식, 빠름) 또는 "json". 결과 사용법은 같다 |
data_ref |
— | 다른 시스템이 넘겨준 data_ref 로 같은 요청을 만든다 (13장) |
trace_id |
자동 | 요청 추적 ID. 지정하지 않으면 서버가 만든다 |
결과가 크면 서버가 여러 조각으로 나눠 보내는데, SDK 가 끝까지 이어 받아 하나의 Batch 로 돌려준다.
조각 사이에 새 데이터나 재정렬본이 들어와도 첫 조각과 같은 판본으로 이어 받는다.
5.2 결과 Batch
| 속성·메서드 | 내용 |
|---|---|
b.series |
시계열 전부. {"채널:tag": Series} |
b.select(채널, tag) |
시계열 하나 → Series |
b.values, b.time_ns |
시계열이 하나면 배열, 여럿이면 {"채널:tag": 배열} |
b.images |
영상 레코드 목록 (dict, 9장) |
b.events |
이벤트 레코드 목록 (dict, 7장) |
b.records |
모든 레코드 (dict 목록, 5.6) |
b.by_modality(m) |
종류별 레코드 ("timeseries", "image", "event") |
b.table |
pyarrow.Table 원본 (format="arrow" 일 때). b.table.to_pandas() 로 바로 DataFrame |
b.gaps |
데이터가 빠진 구간 (6장) |
b.quality |
채널별 품질 요약 (6장) |
b.versions |
채널별 실제로 읽은 판본 {채널: 1} |
b.window |
실제로 적용된 구간 {start_ns, end_ns} |
b.trace_id |
요청 추적 ID — 문의할 때 알려 주면 서버 기록을 찾을 수 있다 |
b.snapshot_id |
스냅샷으로 읽었으면 그 ID |
Series 는 시계열 하나를 numpy 배열로 담는다. 배열들은 같은 길이이고 정렬 시각 순서다.
| 필드 | 형 | 내용 |
|---|---|---|
channel_id, tag, unit |
str | 채널, 항목, 단위 |
time_ns |
int64 배열 | 정렬 시각 (UTC ns) |
values |
float64 배열 | 값 |
tier |
str 배열 | 등급 |
uncertainty_ns |
int64 배열 | 불확도 (모르면 -1) |
5.3 관절 하나 꺼내기
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:00+09:00", purpose="analysis")
s = b.select(F, "elbow_flex/position")
print(s.unit, len(s.values)) # deg 1200
print("최소·최대", s.values.min(), s.values.max())
print("평균 주기 ms", (s.time_ns[-1] - s.time_ns[0]) / (len(s.time_ns) - 1) / 1e6)
print("불확도 최대 ms", s.uncertainty_ns.max() / 1e6)
5.4 모든 관절을 표 하나로 (pandas)
같은 채널의 tag 들은 같은 메시지에서 나왔으므로 시각이 정확히 같다. 시각을 인덱스로 붙이면 관절별 열이 된다.
import pandas as pd
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:00+09:00", purpose="analysis")
df = pd.DataFrame({s.tag.split("/")[0]: pd.Series(s.values, index=pd.to_datetime(s.time_ns, utc=True))
for s in b.series.values()})
df.index = df.index.tz_convert("Asia/Seoul")
print(df.head())
# elbow_flex gripper shoulder_lift shoulder_pan wrist_flex wrist_roll
# 2026-11-16 17:53:40.000756+09:00 94.68 ...
긴 형식(한 줄 = 레코드 하나)이 편하면 arrow 표를 그대로 바꾼다.
import pandas as pd
b = fab.read(dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_state"],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:45+09:00", purpose="analysis")
long = b.table.to_pandas()[["ts_ns", "tag", "value", "unit", "tier", "uncertainty_ns"]]
wide = long.pivot(index="ts_ns", columns="tag", values="value")
print(long.shape, wide.shape) # (1800, 6) (300, 6)
5.5 채널 사이 비교 — 리더암과 팔로우암
채널마다 측정 시각이 다르므로 같은 시각축으로 맞춘 뒤 비교한다. 아래는 팔로우암 시각에 리더암 값을 선형 보간해 추종 오차를 구한다.
import numpy as np
L = "testbed/so101/cell-01/leader-arm/joint_state"
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[L, F],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:00+09:00", purpose="analysis")
for joint in ["shoulder_pan", "shoulder_lift", "elbow_flex", "wrist_flex", "wrist_roll", "gripper"]:
lead, follow = b.select(L, f"{joint}/position"), b.select(F, f"{joint}/position")
lead_at_follow = np.interp(follow.time_ns, lead.time_ns, lead.values) # 팔로우 시각의 리더 값
err = follow.values - lead_at_follow
print(f"{joint:14s} 평균 오차 {err.mean():7.2f} RMS {np.sqrt((err ** 2).mean()):6.2f} {follow.unit}")
보간은 이 문서의 예제가 하는 것이다. 서버는 값을 만들어 내지 않는다(누락 구간도 채우지 않는다, 6장).
5.6 레코드 직접 보기
b.records 는 모든 레코드를 dict 로 준다. 모든 종류에 공통인 필드:
| 필드 | 뜻 |
|---|---|
channel_id |
채널 |
seq |
메시지 번호 (채널 안에서 고유). 같은 메시지에서 나온 시계열 tag 들은 같은 seq |
ts_ns |
정렬 시각 |
aligned |
시각 추정 여부 (Tier-U 면 False) |
tier, uncertainty_ns |
등급, 불확도 (Tier-U 면 불확도 None) |
quality |
GOOD / UNCERTAIN |
correction_version |
판본 |
modality |
timeseries / image / event |
asset_id |
장치 식별자 (aas://partridge-lab/testbed/so101/cell-01/follower-arm) |
시계열 레코드에는 tag, value, unit, sampling_rate_hz 가 더 있다. 영상은 9장, 이벤트는 7장.
b = fab.read(dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_health"],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:43+09:00", purpose="analysis")
for r in b.records[:4]:
print(kst(r["ts_ns"]), r["tag"], r["value"], r["unit"], r["tier"])
5.7 1시간보다 긴 구간
조회는 한 번에 1시간까지다. 더 길면 나눠 부르고 이어 붙인다. 구간이 [start, end) 이므로 경계에서 겹치거나 빠지지 않는다.
여러 시간을 통째로 파일로 받으려면 내보내기(12장)가 낫다.
import numpy as np
from databahn import to_ns
HOUR = 3600 * 10**9
def read_long(fab, start, end, **kw):
"""1시간씩 나눠 조회해 Batch 목록을 돌려준다."""
s, e, out = to_ns(start), to_ns(end), []
while s < e:
out.append(fab.read(start=s, end=min(s + HOUR, e), **kw))
s += HOUR
return out
def concat(batches, channel, tag):
parts = [b.select(channel, tag) for b in batches if f"{channel}:{tag}" in b.series]
return np.concatenate([p.time_ns for p in parts]), np.concatenate([p.values for p in parts])
from datetime import datetime
from zoneinfo import ZoneInfo
seoul = ZoneInfo("Asia/Seoul")
batches = read_long(fab, datetime(2026, 11, 16, 17, 0, tzinfo=seoul), datetime(2026, 11, 16, 19, 30, tzinfo=seoul),
dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_health"],
purpose="analysis")
t, v = concat(batches, "testbed/so101/cell-01/follower-arm/joint_health", "gripper/temperature")
print(len(batches), "번 조회,", len(v), "점, 그리퍼 온도 최고", v.max(), "degC")
5.8 원래 시각 보기 (include_raw_times)
정렬 시각이 어떻게 나왔는지 확인하고 싶을 때 쓴다. 분석에는 정렬 시각만 쓴다.
b = fab.read(dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_state"],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:41+09:00", purpose="analysis",
include_raw_times=True)
r = b.records[0]
print(r["ts_ns"], r["raw_times"])
# raw_times = {ts_source_ns: 장치 자체 시각(없으면 None), ts_gateway_ns: 수집기가 받은 시각, ts_ingest_ns: 셀 로거가 받은 시각}
5.9 arrow 와 json
기본 format="arrow" 는 열 단위 압축 형식으로 받아 numpy 로 바로 바꾼다. 수십만 레코드도 빠르다.
format="json" 은 사람이 읽기 쉬운 대신 크고 느리다. 결과 사용법(select, records 등)은 같고, b.table 만 arrow 일 때 있다.
6. 품질 정보 — 누락, 등급, 판본
서버는 값을 보간하거나 지어내지 않는다. 대신 무엇이 빠졌고 얼마나 믿을 수 있는지를 함께 준다. 분석 전에 확인한다.
6.1 누락 구간 b.gaps
기대 주기의 3배 넘게 기록이 없으면 누락으로 본다.
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F],
start="2026-11-16T19:26:00+09:00", end="2026-11-16T19:26:20+09:00", purpose="analysis")
for g in b.gaps:
print(g["channel_id"].split("cell-01/")[1], kst(g["start_ns"]), "~", kst(g["end_ns"]), g["reason"])
# follower-arm/joint_state 2026-11-16 19:26:00.000 ~ 2026-11-16 19:26:02.577 no_data
# follower-arm/joint_state 2026-11-16 19:26:10.930 ~ 2026-11-16 19:26:20.000 no_data
reason |
뜻 |
|---|---|
no_data |
구간 앞이나 뒤가 통째로 비었다 (장치가 꺼져 있었음) |
missing |
기록 중간에 빠졌다 (통신 끊김 등) |
6.2 품질 요약 b.quality
for ch, q in b.quality.items():
print(ch.split("cell-01/")[1], q)
# follower-arm/joint_state {'tier': {'Tier-3': 1.0}, 'max_uncertainty_ns': 15000000, 'missing_ratio': 0.582,
# 'excluded_count': 0, 'delivery_delay': {'p50_ns': 344500, 'p95_ns': 643000}}
| 필드 | 뜻 |
|---|---|
tier |
등급 분포 (비율) |
max_uncertainty_ns |
가장 큰 불확도 |
missing_ratio |
구간 중 누락 비율 (0~1). 위 예는 20초 중 58% 가 비었다 |
excluded_count |
min_tier·미추정 때문에 뺀 레코드 수 |
delivery_delay |
측정 순간부터 서버에 들어오기까지 걸린 시간 (p50, p95) |
quality 에는 요청한 채널이 모두 들어 있다. 데이터가 없는 채널은 missing_ratio 가 1.0 이다.
조건에 맞는 레코드가 하나도 없어도 오류가 아니다 — 빈 Batch 가 온다. len(b.records) == 0 이나 missing_ratio 로 확인한다.
6.3 등급으로 거르기
b = fab.read(dataset_id="plab-testbed-cell01", start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:50+09:00",
purpose="analysis", min_tier="Tier-3") # 불확도 100 ms 넘는 레코드는 뺀다
print({ch.split("cell-01/")[1]: q["excluded_count"] for ch, q in b.quality.items()})
s = b.select("testbed/so101/cell-01/follower-arm/joint_state", "gripper/position")
tight = s.values[(s.uncertainty_ns >= 0) & (s.uncertainty_ns <= 25_000_000)] # 더 엄격하게: 불확도 25 ms 이내만
print(len(s.values), len(tight)) # 600 600 (이 구간의 관절은 모두 22 ms 이내)
6.4 판본
print(b.versions) # {'testbed/so101/cell-01/follower-arm/joint_state': 1, ...}
같은 구간도 나중에 재정렬되면(시각 계산을 고쳐 다시 기록) 판본이 올라가고, 조회는 새 판본을 준다.
그래서 같은 요청이라도 시점에 따라 값이 조금 달라질 수 있다. 결과를 고정해야 하면 스냅샷(11장)을 쓴다.
재정렬이 있었는지는 fab.dataset(id)["corrections"] 에 나온다.
7. 이벤트 — 작업(에피소드)
작업자는 콘솔에서 작업 시작(start)과 끝(ok/fail)을 입력한다. 서버는 이 입력을 에피소드 구간 이벤트로 묶어 준다.
작업자 입력은 시각을 추정할 수 없어(사람의 반응 지연) Tier-U 이므로 include_unaligned=True 가 필요하다.
7.1 에피소드 목록
ev = fab.events(dataset_id="plab-testbed-cell01",
start="2026-11-16T00:00:00+09:00", end="2026-11-17T00:00:00+09:00",
purpose="analysis", include_unaligned=True, event_types=["episode"])
for e in ev["events"]:
print(e["episode_id"], kst(e["start_ns"]), "~", kst(e["end_ns"]),
f"{(e['end_ns'] - e['start_ns']) / 1e9:.1f}초", e["task"], e["inspection_result"],
"폐기" if e["discarded"] else "", e["status"])
# ep-20261116T085339Z 2026-11-16 17:53:39.657 ~ 2026-11-16 17:54:08.453 28.8초 칼집기 success closed
| 인자 | 설명 |
|---|---|
dataset_id / snapshot_id, start, end, window, channels, purpose, min_tier, include_unaligned |
read 와 같다 |
event_types |
고를 종류. 생략하면 전부 (episode 구간 + 아래 점 이벤트) |
| (구간 한도) | 이벤트 조회는 한 번에 31일까지 (값 조회의 1시간보다 길다) |
에피소드(event_type == "episode") 필드:
| 필드 | 뜻 |
|---|---|
episode_id (= event_id) |
에피소드 ID (ep-<시작 UTC>) |
start_ns, end_ns |
시작·끝 시각 (작업자 입력 시각) |
task |
작업 이름 |
operator_id |
작업자 |
inspection_result |
success(ok) / fail |
discarded |
작업자가 이 에피소드를 폐기했는지 (discard). 학습에서 빼야 한다 |
marks_ns |
작업 중 표시(mark)한 시각 목록 |
status |
closed(시작·끝 다 있음) / open(아직 안 끝남) / start_unknown(시작이 구간 밖) |
derived_from |
이 구간을 만든 점 이벤트들의 ID |
점 이벤트(event_types 로 고른다): episode_start, episode_stop, episode_discard, episode_mark.
필드는 같고 start_ns == end_ns, 작업자가 쓴 메모는 note, 콘솔 입력 시각은 ts_entry_ns.
응답의 나머지 키: versions(판본), window(적용 구간), excluded_count, trace_id.
7.2 성공률 집계
from collections import Counter
ev = fab.events(dataset_id="plab-testbed-cell01", start="2026-11-01T00:00:00+09:00", end="2026-12-01T00:00:00+09:00",
purpose="analysis", include_unaligned=True, event_types=["episode"])["events"]
valid = [e for e in ev if e["status"] == "closed" and not e["discarded"]]
print(Counter((e["task"], e["inspection_result"]) for e in valid))
print("평균 작업 시간", sum(e["end_ns"] - e["start_ns"] for e in valid) / len(valid) / 1e9, "초")
8. 연결키 — 특정 작업의 데이터만
에피소드 구간 안에 든 관절·영상 데이터를 "그 에피소드의 데이터"로 고르는 기능이다. 데이터셋의 link_rules 에 정의되어 있고,
테스트베드의 연결키는 episode_id 하나다.
ep = "ep-20261116T085339Z"
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[F],
start="2026-11-16T17:53:00+09:00", end="2026-11-16T17:55:00+09:00",
purpose="analysis", link_filter={"episode_id": ep})
s = b.select(F, "gripper/position")
print(len(s.values), kst(s.time_ns[0]), "~", kst(s.time_ns[-1]))
# 1605 2026-11-16 17:53:40.684 ~ 2026-11-16 17:54:07.425 (에피소드 17:53:39.657~17:54:08.453 의 경계 ±약 1초 안쪽만)
조회 구간(start~end)은 에피소드를 덮도록 넉넉히 준다. 에피소드 시각은 7장으로 찾는다.
경계 판정. 작업자 입력 시각은 약 1초 불확도가 있어서 경계 근처 데이터는 확실히 안인지 밖인지 알 수 없다.
| 판정 | 조건 | 기본 동작 |
|---|---|---|
inside |
두 경계 모두와의 시각 차가 (데이터 불확도 + 경계 불확도)보다 크다 | 포함 |
ambiguous |
경계와 너무 가깝다 | 제외 (link_ambiguous="include" 면 포함) |
| (없음) | 구간 밖 | 제외 |
거르지 않고 레코드마다 어느 에피소드에 속하는지만 붙이려면 link_keys 를 쓴다.
b = fab.read(dataset_id="plab-testbed-cell01", channels=["testbed/so101/cell-01/follower-arm/joint_state"],
start="2026-11-16T17:53:38+09:00", end="2026-11-16T17:53:42+09:00", purpose="analysis",
link_keys=["episode_id"])
from collections import Counter
print(Counter(str((r.get("links") or {}).get("episode_id", {}).get("match")) for r in b.records))
# Counter({'None': ..., 'ambiguous': ..., 'inside': ...}) — None 은 어느 에피소드에도 안 속함
9. 영상
9.1 영상 레코드
조회 결과의 영상 레코드에는 이미지 본문 대신 본문을 받을 수 있는 참조(content_ref)가 들어 있다.
수천 장을 한꺼번에 받지 않고 필요한 프레임만 받기 위해서다.
W = "testbed/so101/cell-01/wrist-cam/image"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[W],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:53:41+09:00", purpose="analysis")
print(len(b.images), "프레임") # 29 (30 fps, 1초)
img = b.images[0]
print({k: img[k] for k in ["ts_ns", "format", "resolution", "is_keyframe", "uncertainty_ns", "content_hash"]})
| 필드 | 뜻 |
|---|---|
ts_ns |
노출 중앙 시각 (정렬 시각) |
format, resolution |
jpeg, 640x480 |
content_ref |
본문 참조. fab.content 에 넘긴다. 서버가 서명한 값이라 고치면 거부된다 |
content_hash |
본문 sha256. 받은 바이트를 확인할 수 있다 |
is_keyframe |
JPEG 는 모든 프레임이 독립이라 늘 True |
roi, product_key |
테스트베드는 None |
9.2 이미지 받기·저장·디코드
import hashlib
from pathlib import Path
jpeg = fab.content(img["content_ref"], purpose="analysis") # bytes
assert hashlib.sha256(jpeg).hexdigest() == img["content_hash"]
Path("frames").mkdir(exist_ok=True)
Path(f"frames/wrist_{img['ts_ns']}.jpg").write_bytes(jpeg)
import io
from PIL import Image
im = Image.open(io.BytesIO(jpeg))
print(im.size, im.mode) # (640, 480) RGB
# numpy 배열: np.asarray(im) / OpenCV: cv2.imdecode(np.frombuffer(jpeg, np.uint8), cv2.IMREAD_COLOR)
9.3 프레임과 같은 순간의 관절 값
영상과 관절은 주기가 다르므로 프레임 시각에 가장 가까운 관절 샘플을 찾는다.
import numpy as np
W = "testbed/so101/cell-01/wrist-cam/image"
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[W, F],
start="2026-11-16T17:53:45+09:00", end="2026-11-16T17:53:46+09:00", purpose="analysis")
grip = b.select(F, "gripper/position")
for img in b.images[::10]: # 3장만
i = np.clip(np.searchsorted(grip.time_ns, img["ts_ns"]), 1, len(grip.time_ns) - 1)
i = i - 1 if img["ts_ns"] - grip.time_ns[i - 1] < grip.time_ns[i] - img["ts_ns"] else i
gap_ms = abs(int(grip.time_ns[i]) - img["ts_ns"]) / 1e6
print(kst(img["ts_ns"]), f"그리퍼 {grip.values[i]:.1f}", f"(시각 차 {gap_ms:.1f} ms,",
f"불확도 영상 {img['uncertainty_ns'] / 1e6:.0f} ms / 관절 {grip.uncertainty_ns[i] / 1e6:.0f} ms)")
시각 차가 두 불확도보다 작으면 "같은 순간"으로 볼 수 있다. 테스트베드에서는 수십 ms 단위까지만 의미가 있다.
10. 최신값
채널마다 마지막으로 저장된 값을 준다. 대시보드의 "현재 상태" 같은 데 쓴다.
lat = fab.latest(dataset_id="plab-testbed-cell01", purpose="display",
channels=["testbed/so101/cell-01/follower-arm/joint_health"])["latest"]
for ch, v in lat.items():
print(ch.split("cell-01/")[1], kst(v["ts_ns"]), f"{v['age_ns'] / 1e9:.0f}초 전")
for r in v["records"][:4]:
print(" ", r["tag"], r["value"], r["unit"])
| 필드 | 뜻 |
|---|---|
ts_ns |
마지막 메시지의 정렬 시각 |
age_ns |
지금으로부터 얼마나 지났는지 |
records |
그 메시지의 레코드들 (관절 tag 전부) |
correction_version, closed_until_ns |
판본, 저장이 끝난 시각 |
실시간이 아니다. 서버는 저장이 끝난 파일만 보므로, 기록 중인 데이터는 파일이 닫히는(최대 10분) 뒤에 나타난다.
11. 스냅샷 — 학습 데이터 고정
조회는 늘 최신 판본을 주므로 같은 요청도 나중에 결과가 달라질 수 있다(6.4). 학습·평가는 같은 데이터를 다시 읽을 수 있어야 하므로
"이 구간·이 채널의 지금 판본 파일 목록"을 고정해 이름(snapshot_id)을 붙인다. 같은 snapshot_id 는 언제 읽어도 같은 데이터다.
11.1 만들기
snap = fab.create_snapshot(
dataset_id="plab-testbed-cell01",
start="2026-11-16T17:53:39+09:00", end="2026-11-16T17:54:09+09:00",
channels=["testbed/so101/cell-01/leader-arm/joint_state",
"testbed/so101/cell-01/follower-arm/joint_state",
"testbed/so101/cell-01/wrist-cam/image"],
purpose="training", label="grip-2026w47")
print(snap["snapshot_id"], snap["file_count"], snap["status"])
| 인자 | 설명 |
|---|---|
dataset_id, start/end (또는 window) |
고정할 범위. 길이 제한은 없다. 범위에 저장된 파일이 하나도 없으면 DAT-4001 |
channels |
고를 채널. 생략하면 전부 |
purpose |
training / evaluation / audit 중 하나 |
label |
사람이 알아볼 이름 (선택) |
응답 필드:
| 필드 | 뜻 |
|---|---|
snapshot_id |
이후 조회·내보내기에 쓰는 ID |
scope |
{dataset_id, channels, window} 고정한 범위 |
items |
채널별 {file_count, correction_version, hash_digest} — 고정된 파일과 판본 |
coverage |
채널별 실제 데이터의 처음·끝 |
status |
active / released(더 이상 보존하지 않음) |
referenced_by |
이 스냅샷으로 학습한 모델 목록 |
algorithm_version |
판본 선택 방식 버전 |
11.2 읽기·목록
sid = fab.snapshots("plab-testbed-cell01")[0]["snapshot_id"] # 목록은 최신순 → 방금 만든 것
b = fab.read(snapshot_id=sid, purpose="training") # 구간을 생략하면 스냅샷 전체
print(b, b.snapshot_id, b.window)
ev = fab.events(snapshot_id=sid, purpose="training", include_unaligned=True) # 이벤트도 같은 방식
print(fab.snapshot(sid)["scope"])
스냅샷의 일부 구간만 읽으려면 start/end 를 함께 준다. 나중에 재정렬본이 생겨도 스냅샷은 고정된 판본을 계속 준다.
read 의 1시간 한도는 스냅샷에도 적용된다(스냅샷 구간으로 자른 뒤의 길이 기준). 1시간 넘는 스냅샷은 start/end 로 나눠 읽거나
Parquet 로 내보낸다(12장).
11.3 모델 기록
스냅샷으로 학습한 모델을 기록해 두면 "이 모델은 어떤 데이터로 학습했나"를 추적할 수 있고, 그 스냅샷의 파일은 보존된다.
fab.add_model_reference(sid, package_id="pkg-grip-policy", version="1.0.0")
print(fab.snapshot(sid)["referenced_by"])
12. 내보내기 — 파일로 받기
조회는 1시간 한도가 있고 메모리로 받는다. 큰 데이터를 파일로 받으려면 내보내기를 쓴다. 서버가 뒤에서 파일을 만들고(비동기 작업), 다 되면 내려받는다.
kind |
형식 | 쓰는 곳 | 범위 |
|---|---|---|---|
"parquet" |
종류별 Parquet + manifest.json | 학습 (pandas, PyTorch 등) | 스냅샷 필수 |
"mcap" |
MCAP 파일 하나 | Foxglove 재생, ROS 도구 | 데이터셋 + 구간, 또는 스냅샷 |
내보내기는 데이터를 밖으로 가져가는 일이라 조회보다 한 단계 더 확인한다: 내 토큰의 현장이 데이터셋 현장과 다르면(현장 밖)
internal 데이터는 내보내기 승인(export_scope=off_site_approved)이 있어야 하고, restricted 는 내보낼 수 없다 (2.1).
승인이 없으면 DAT-4031 "현장 밖 내보내기 승인 없음". 같은 확인을 파일을 받을 때 한 번 더 한다.
12.1 Parquet (학습용)
job = fab.export("parquet", snapshot_id=sid, purpose="training")
job.wait() # 끝날 때까지 기다린다 (기본 600초)
paths = job.download("out/train") # 받으면서 sha256 확인
print([p.name for p in paths]) # ['image.parquet', 'timeseries.parquet', 'manifest.json']
import pandas as pd
ts = pd.read_parquet("out/train/timeseries.parquet")
print(ts.columns.tolist())
print(ts.groupby(["channel_id", "tag"]).size().head())
| 파일 | 내용 (열) |
|---|---|
timeseries.parquet |
channel_id, seq, ts_ns, aligned, tier, uncertainty_ns, quality, correction_version, ts_gateway_ns, ts_ingest_ns, asset_id, tag, value, unit, sampling_rate_hz |
image.parquet |
위 공통 열 + format, resolution, content_hash, content_ref (본문은 fab.content 로) |
event.parquet |
이벤트가 있을 때. 7장의 필드 |
manifest.json |
요청 범위, 파일별 크기·sha256·레코드 수, gaps, quality_summary, 판본 |
12.2 MCAP (Foxglove 재생용)
job = fab.export("mcap", dataset_id="plab-testbed-cell01",
start="2026-11-16T17:53:39+09:00", end="2026-11-16T17:54:09+09:00",
channels=["testbed/so101/cell-01/leader-arm/joint_state",
"testbed/so101/cell-01/follower-arm/joint_state"],
purpose="display")
paths = job.wait().download("out/mcap")
print(paths[0], paths[0].stat().st_size // 1024, "KB")
- 여러 원본 파일(관절·카메라, 10분 경계, 판본)에 걸쳐 있어도 파일 하나로 합쳐 최신 판본만 담는다.
- MCAP 의 메시지 시각(
log_time)이 정렬 시각이라 Foxglove 에서 채널들이 정렬된 상태로 재생된다. - 카메라 두 대가 들어가면 1분에 약 120 MB. 관절만 필요하면
channels로 줄인다. - 조회와 달리 1시간 한도가 없다. 긴 구간은
job.wait(timeout=1800)처럼 기다리는 시간을 늘린다.
12.3 내보내기 인자와 작업 객체
fab.export 인자 |
설명 |
|---|---|
kind |
"parquet" / "mcap" |
snapshot_id 또는 dataset_id + start/end |
범위. parquet 는 스냅샷만 |
channels, min_tier, include_unaligned |
조회와 같다 |
purpose |
목적. 학습용은 training |
label |
사람이 알아볼 이름 |
ExportJob |
내용 |
|---|---|
job.export_id |
작업 ID |
job.status |
마지막으로 받은 상태 dict. status 는 PENDING → RUNNING → SUCCEEDED / FAILED |
job.refresh() |
상태를 다시 받는다 |
job.wait(timeout=600, poll=1.0) |
끝날 때까지 기다린다. 실패면 FabricError, 시간 초과면 TimeoutError |
job.files |
결과 파일 목록 [{name, size, sha256}] |
job.download(폴더) |
모두 내려받고 sha256 을 확인해 경로 목록을 돌려준다 |
기다리지 않고 나중에 받으려면 export_id 를 저장해 두었다가 작업 객체를 다시 만든다.
from databahn import ExportJob
eid = job.export_id # 저장해 둔 ID
again = ExportJob(fab, {"export_id": eid, "status": "PENDING"}).wait()
print(again.status["status"], [f["name"] for f in again.files])
12-1. 데이터 사전 매핑 — 채널의 뜻을 표준 항목으로
데이터 사전(항목 ID·이름·정의·단위)은 TTA 가 관리한다. 조회 서비스는 "이 채널(또는 필드)은 사전의 어느 항목인가"라는
매핑만 등록·조회한다. 같은 항목을 가진 다른 설비의 채널을 찾거나, 모델 입력(IF-20 semantic_id)을 어느 설비에 붙일 수 있는지 볼 때 쓴다.
# 조회 (인증된 누구나)
m = fab.mapping("channel", "testbed/so101/cell-01/follower-arm/joint_state")
print(m["active"]) # 지금 매핑 (없으면 None): dict_item_id, dict_version, verification …
for x in fab.mappings_for_item("TTA-GRIP-POS"): # 같은 사전 항목을 가진 채널·필드
print(x["target_type"], x["target_id"])
print(fab.dataset("plab-testbed-cell01")["channels"][0]["semantic_id"]) # 카탈로그에도 나온다
등록·교체·사용 중지는 관리 권한(dict_admin) 토큰만 할 수 있다.
m1 = fab.register_mapping("tag", "testbed/so101/cell-01/follower-arm/joint_state#gripper/position", "TTA-GRIP-POS", "1")
m2 = fab.register_mapping("tag", m1["target_id"], "TTA-GRIP-POS", "2", replaces=m1["mapping_id"]) # 새 버전으로 교체
fab.deprecate_mapping(m2["mapping_id"]) # 사용 중지 (지우지 않음)
| 알아 둘 것 | |
|---|---|
| 대상 | channel, field(규약 필드 이름, 예 ts_aligned), dataset_field, tag(<채널>#<tag>, 테스트베드 확장) |
| 교체 | 활성 매핑이 있는 대상에 다른 항목을 등록하려면 replaces=<지금 mapping_id>. 없으면 DAT-4093. 같은 매핑을 다시 등록하면 그대로 (created=False) |
verification |
TTA 사전 연동 전에는 unverified (항목이 실제로 있는지 확인 못 함). 연동 뒤 관리자가 다시 확인한다 |
| 보이는 범위 | 채널·tag 매핑은 그 데이터셋 권한이 있어야 보인다 |
모델 입력을 사전 항목으로 선언할 때(IF-20 data_requirements) 쓰는 두 함수:
fab.semantic_of(channel_id, tag=None) # 채널(또는 tag)의 지금 사전 항목. tag 매핑이 우선
fab.resolve_semantic("plab-testbed-cell01", "TTA-GRIP-POS", select={"channel": "*/follower-arm/*"})
# → [{"channel_id", "tag", "target_type", "mapping_id", "dict_version"}] 비면 대응 없음, 둘 이상이면 select 를 좁힌다
12-2. 창 — 모델 입력 텐서 만들기 (databahn.window)
모델 입력은 "구간 하나 → 고정 칸 수 텐서"다. 학습(스냅샷을 내보낸 parquet)과 추론(IF-03 조회)이 같은 규칙으로 텐서를 만들어야 학습과 서빙이 어긋나지 않는다. 창을 직접 자르지 말고 이 모듈을 쓴다 (IF-20 데이터 요구의 규칙과 같다).
from databahn import window as W
JOINTS = [f"{j}/position" for j in ("shoulder_pan", "shoulder_lift", "elbow_flex", "wrist_flex", "wrist_roll", "gripper")]
spec = W.Spec(window_ns=1_000_000_000, steps=60, min_tier="Tier-3", max_missing_ratio=0.05, inputs=[
W.Input("state", channel="testbed/so101/cell-01/follower-arm/joint_state", tags=JOINTS), # tags = 마지막 축 순서
])
w = W.read(fab, spec, dataset_id="plab-testbed-cell01", start="2026-11-16T17:53:40+09:00", purpose="analysis")
w.tensors["state"].shape # (60, 6) float32, 빈 칸은 NaN
w.missing_ratio, w.quality # {"state": 0.0}, {"tier": {...}, "min_tier": "Tier-3", "versions": {채널: [판본]}}
ws = W.from_export("내려받은_내보내기_폴더", spec, stride_ns=500_000_000) # 학습: 창 여러 개 [N, 60, 6]
spec.requirements(modes=["sync"]) # IF-20 manifest 의 data_requirements
| 규칙 | |
|---|---|
| 시간축 | 정렬 시각만. 미추정(Tier-U)과 min_tier 미달은 뺀다 |
| 격자 | 창 [start, start + window_ns) 를 steps 칸으로(정수 경계). 칸마다 그 칸 안의 마지막 값 |
| 누락 | 보간하지 않는다. 빈 칸은 NaN (fill="hold" 면 앞 칸 값 유지). 누락 비율 = 빈 칸 / 전체 칸. max_missing_ratio 를 넘는 창은 학습에서 빠지고(dropped), 추론에서는 usable() 가 False |
| tag | 채널에 데이터가 있는데 요청한 tag 가 없으면 오류 (빈 구간은 NaN, tag 이름 실수는 오류). 관절 명령의 tag 는 <관절>/sent_position·requested_position |
| 격자 칸 수 | 표본 주기보다 넓게 잡는다. 60 Hz 관절을 60칸/초로 나누면 표본 간격 흔들림으로 빈 칸이 생긴다 (실측: 30칸이면 모든 창이 누락 5% 이하) |
| 채널 고르기 | channel(채널 ID·패턴) 또는 semantic_id + select(12-1). spec.resolve(fab, 데이터셋) 이 하나로 풀리지 않으면 WindowError (none·ambiguous) |
| 학습 → 사전 항목 | spec.with_semantics(fab): 채널로 정의한 입력에 IF-03 매핑의 semantic_id 와 select(장치 패턴)를 채운다 |
12-3. 모델 추론 — databahn.Models (IF-20)
학습한 모델은 IF-20 게이트웨이에 등록·배포되고, 추론도 게이트웨이로 부른다. Models 는 그 클라이언트다.
토큰은 IF-03 과 같다. 다만 토큰에 IF-20 권한(scope)이 붙어 있어야 한다: 추론 if20.infer, 조회 if20.read,
배포·롤백 if20.deploy (관리자에게 요청). HTTP 형식은 API 명세 10장.
from databahn import Models
m = Models("https://if20.data-bahn.com", site_id="partridge-lab") # 키는 Fabric 과 같은 환경 변수에서
# 주소를 빼면 IF20_URL, 그다음 FABRIC_URL (IF-03 주소로도 /if20 이 연결된다)
m.health() # {"status": "DEGRADED", "endpoints": [{..., "current": {"version": "0.1.0", "ready": True}, "previous": None}]}
m.deployments() # [{"package_id": "so101-tracking-baseline", "version": "0.1.0", "role": "current", ...}]
m.metadata("so101-tracking-baseline")["inputs"]
# [{'name': 'command', 'datatype': 'FP32', 'shape': [-1, 30, 6]}, {'name': 'state', 'datatype': 'FP32', 'shape': [-1, 30, 6]}]
12-3.1 참조 전달 — 데이터 위치만 보낸다
데이터셋과 창 시작만 주면 게이트웨이가 모델의 데이터 요구(창 1초, 30칸, Tier-3 이상, 누락 5% 이하)대로 IF-03 에서 읽는다.
읽는 권한은 내 토큰의 inference 권한으로 판정한다 (게이트웨이가 내 대신 읽고, IF-03 접근 기록에 내 이름이 남는다).
p = m.infer("so101-tracking-baseline", dataset_id="plab-testbed-cell01", start="2026-11-18T11:10:20Z")
p.value # array([[2.2844577]], dtype=float32) — 출력이 하나면 그 배열 (여럿이면 p.outputs[이름])
p.version # '0.1.0' — 이 현장의 current
p.latency_ms # 122.4 — 게이트웨이 처리 시간
p.data_quality # {'tier': {'Tier-3': 1.0}, 'min_tier': 'Tier-3', 'missing_ratio': {'command': 0.0, 'state': 0.0}}
p.data_window # {'start_ns': ..., 'end_ns': ..., 'if03_dataset': 'plab-testbed-cell01', 'time_basis': 'aligned'}
p.semantic_resolution # 입력 → 채널 (배포 때 사전 매핑으로 고정한 것)
p.semantic_drift # [] — 고정한 매핑이 그 뒤 사용 중지되면 여기에 (아래)
p.trace_id
매핑이 바뀌면 (semantic_drift): 사전 관리자가 채널의 매핑을 새 판으로 교체해도 이미 배포된 모델의 입력은 바뀌지 않는다.
고정한 채널로 계속 추론하고, 응답에 사용 중지된 매핑과 대체 매핑을 알린다. 다시 배포할지는 운영 기관이 정한다.
for d in p.semantic_drift:
print(d["input"], d["mapping_id"], d["status"], "→ 대체", d["replacement"])
# state map-… deprecated → 대체 {'mapping_id': 'map-…', 'dict_item_id': '…', 'dict_version': '2'}
end 를 주면 모델 창 길이와 같아야 한다. 다른 시스템에서 받은 data_ref(13장)는 m.infer(pkg, data_ref=ref) 로 그대로.
12-3.2 값 전달 — 내가 만든 텐서를 보낸다
12-2 의 창 모듈로 만든 Window 를 그대로 넘기면 텐서와 창 구간이 함께 간다. 같은 창이면 참조 전달과 결과가 같다.
from databahn import Fabric, window
fab = Fabric("https://if03.data-bahn.com")
man = m.version("so101-tracking-baseline", "0.1.0")["manifest"]
spec = window.Spec.from_requirements(man["data_requirements"]) # 모델과 같은 창 규칙
w = window.read(fab, spec, dataset_id="plab-testbed-cell01", start="2026-11-18T11:10:20Z", purpose="inference")
m.infer("so101-tracking-baseline", window=w).value # array([[2.2844577]]) — 참조 전달과 같다
배열을 직접 줄 때는 그 배열을 만든 창 구간(data_window)을 함께 준다. 2차원 [칸, 원소] 는 배치 축을 붙여 보낸다. NaN 은 빈 칸으로 간다.
import numpy as np
m.infer("so101-tracking-baseline",
inputs={"state": state_30x6, "command": command_30x6},
data_window={"start_ns": t0, "end_ns": t0 + 1_000_000_000})
값 전달에서는 데이터 품질·판본을 게이트웨이가 모른다 (p.data_quality is None). 품질 확인은 w.missing_ratio·w.quality 로 직접.
12-3.3 버전 고르기, 시간 제한
m.infer(pkg, version="0.2.0", dataset_id=..., start=...) # current 가 아닌 버전 (previous 로 비교할 때)
m.infer(pkg, ..., timeout_ms=10_000) # 동기 제한, 기본 3초·최대 10초 (넘으면 MDL-5040)
m.infer(pkg, ..., trace_id="tr-my-run-001") # 내 추적 ID — 감사 기록·IF-03 접근 기록까지 이어진다
12-3.4 패키지 찾기
m.packages() # [{"package_id", "version", "semantic_ids", "lifecycle", "owner"}]
m.packages(semantic_id="<사전 항목>") # 그 물리량을 입력으로 쓰는 모델만
v = m.version("so101-tracking-baseline", "0.1.0")
v["manifest"]["inputs"], v["training_history"]["snapshot_id"], v["deployments"]
m.applicability("so101-tracking-baseline", "0.2.0")["applicable"] # 이 현장 데이터로 입력을 풀 수 있는지
12-3.5 배포·롤백 (scope if20.deploy)
job = m.deploy("so101-tracking-baseline", "0.2.0") # 끝날 때까지 기다린다 (실측 약 9초)
job.result["resolved_inputs"] # 배포 때 고정한 입력 채널
m.rollback("so101-tracking-baseline", reason="점수 이상") # {"current": "0.1.0", "rolled_back": "0.2.0", ...}
- 배포는 current 를 교체한다. 이전 current 는 previous 로 남고, 그 전 previous 는 은퇴한다. 롤백된 버전은 previous 가 되지 않는다.
- 실패하면
ModelError(서명 불일치 MDL-4091, 자원 부족 MDL-5071, 입력을 풀 수 없음 MDL-4223, 준비 시간 초과 MDL-5031). 실패해도 기존 current 는 그대로 서비스한다. wait=False면 작업만 받는다:job = m.deploy(..., wait=False)→job.refresh(),job.wait(), 나중에m.job(job_id).- 연구자 시험 배포 (scope
if20.deploy:test): 시험 현장partridge-lab-test에만 배포·롤백할 수 있다. 운영 현장은 MDL-4031. 시험 현장은 운영과 같은 셀 데이터를 읽고, 운영 현장의 current·previous 에는 영향이 없다. 모델 manifest 의sites에 시험 현장이 있어야 한다.
r = Models("https://if20.data-bahn.com") # 연구자 토큰
r.deploy("so101-tracking-baseline", "0.4.0", site_id="partridge-lab-test")
r.infer("so101-tracking-baseline", site_id="partridge-lab-test", dataset_id="plab-testbed-cell01", start="…").value
- 같은 호출을 다시 시도해도 한 번만 일어나도록 SDK 가 멱등 키를 붙인다.
12-3.6 오류
from databahn import ModelError
try:
m.infer("so101-tracking-baseline", dataset_id="plab-testbed-cell01", start="2026-11-18T09:00:00Z") # 녹화 없는 시각
except ModelError as e:
print(e.code, e.cause, e.p4_code, e.retryable, e.message, e.trace_id)
print(e.detail)
# MDL-4221 None None False 누락 비율 1.000 > 허용 0.05 tr-…
# {'data_quality': {'tier': {}, 'min_tier': None, 'missing_ratio': {'command': 1.0, 'state': 1.0}}}
| 코드 | 흔한 원인 | 대응 |
|---|---|---|
| MDL-4031 | scope 없음, 또는 그 데이터셋의 inference 권한 없음(e.cause = DAT-4031) |
관리자에게 권한 요청 |
| MDL-4042 | 현장에 배포된 버전 없음, 롤백할 previous 없음 | m.deployments() 확인 |
| MDL-4221 | 창에 데이터가 모자람(녹화 없는 구간·누락 5% 초과·등급 미달), 값 전달 shape 불일치 | 녹화가 있는 시각으로, e.detail 확인 |
| MDL-5031·5040 | 서빙 준비 중, 시간 제한 초과 | SDK 가 MDL-5031 은 자동 재시도. 5040 은 timeout_ms 를 늘리거나 다시 |
전체 표는 API 명세 10.7.
13. data_ref — 다른 시스템과 같은 데이터 가리키기
다른 시스템(IF-20 등)이 "이 데이터"를 가리킬 때 data_ref 라는 dict 를 넘긴다. 받은 쪽은 그대로 read 에 넘기면 같은 요청이 된다.
ref = {"if03_dataset": "plab-testbed-cell01",
"channels": ["testbed/so101/cell-01/follower-arm/joint_state"],
"window": {"start": "2026-11-16T17:53:40+09:00", "end": "2026-11-16T17:53:41+09:00"},
"min_tier": "Tier-3"}
b = fab.read(data_ref=ref, purpose="analysis")
print(b)
data_ref 의 키: if03_dataset 또는 snapshot_id, channels, window, min_tier. 학습 데이터를 가리킬 때는 snapshot_id 를 쓴다(값이 고정).
14. 오류 처리
서버 오류는 모두 FabricError 로 온다. (모델 추론 Models 의 오류는 ModelError, 12-3.6)
from databahn import FabricError
try:
fab.read(dataset_id="plab-testbed-cell01", start="2026-11-16T17:00:00+09:00",
end="2026-11-16T18:30:00+09:00", purpose="analysis")
except FabricError as e:
print(e.code, e.status, e.message, e.trace_id)
# DAT-4002 400 구간이 한도(3600초)를 넘음. 나눠서 조회하거나 내보내기를 쓰세요 tr-…
| 코드 | HTTP | 뜻 | 대응 |
|---|---|---|---|
| DAT-4001 | 400 | 요청 형식 오류 (필수 값 없음, 구간 역전, 시간대 없는 시각, 잘못된 값) | 메시지대로 요청 수정 |
| DAT-4002 | 400 | 구간·응답 크기 한도 초과 (조회 1시간) | 나눠 조회(5.7) 또는 내보내기(12장) |
| DAT-4011 | 404 | 데이터셋에 없는 채널, 또는 남의 내보내기 작업 | 채널 이름 확인 (fab.dataset(id)["channels"]) |
| DAT-4031 | 403 | 권한 없음: 토큰이 틀리거나 만료됨, 그 데이터셋·목적 권한 없음(데이터셋 이름이 틀려도 같다), 현장 밖 내보내기 승인 없음 | 키·allowed_purposes 확인, 관리자에게 요청 |
| DAT-4032 | 403 | 보안 등급 제한 (restricted 는 현장 안 소비자만) | — |
| DAT-4041 | 404 | 스냅샷 없음, 또는 released | ID 확인 |
| DAT-4091 | 409 | 파일 해시 불일치 (저장 파일 변조·손상 감지, 또는 내려받기 중 손상) | 다시 받기. 반복되면 관리자에게 trace_id 와 함께 |
| DAT-5031 | 503 | 서비스 일시 장애 | SDK 가 retries 번 자동 재시도 |
| DAT-5041 | — | 내보내기 작업 실패 | job.status["error"] 확인 |
SDK 자체 예외: 키가 없으면 ValueError(연결 때), 시간대 없는 datetime 이면 ValueError, job.wait 시간 초과면 TimeoutError.
문의할 때는 trace_id(e.trace_id, b.trace_id)를 함께 알려 주면 서버 기록에서 그 요청을 찾을 수 있다.
15. 레시피
15.1 에피소드마다 관절 궤적 배열 만들기 (학습 입력)
import numpy as np
DS = "plab-testbed-cell01"
L = "testbed/so101/cell-01/leader-arm/joint_state"
F = "testbed/so101/cell-01/follower-arm/joint_state"
JOINTS = ["shoulder_pan", "shoulder_lift", "elbow_flex", "wrist_flex", "wrist_roll", "gripper"]
eps = fab.events(dataset_id=DS, start="2026-11-16T00:00:00+09:00", end="2026-11-17T00:00:00+09:00",
purpose="training", include_unaligned=True, event_types=["episode"])["events"]
episodes = {}
for e in eps:
if e["status"] != "closed" or e["discarded"]:
continue
b = fab.read(dataset_id=DS, channels=[L, F], start=e["start_ns"] - 2 * 10**9, end=e["end_ns"] + 2 * 10**9,
purpose="training", min_tier="Tier-3", link_filter={"episode_id": e["episode_id"]})
t = b.select(F, "gripper/position").time_ns # 팔로우 시각을 기준 축으로
obs = np.stack([b.select(F, f"{j}/position").values for j in JOINTS], axis=1) # (N, 6) 상태
act = np.stack([np.interp(t, b.select(L, f"{j}/position").time_ns, b.select(L, f"{j}/position").values)
for j in JOINTS], axis=1) # (N, 6) 리더 = 행동
episodes[e["episode_id"]] = {"t_ns": t, "obs": obs, "act": act, "success": e["inspection_result"] == "success"}
print(e["episode_id"], obs.shape, act.shape, e["inspection_result"])
재현이 필요하면 이 구간들로 스냅샷을 만든 뒤(11장) snapshot_id 로 읽는다.
15.2 그래프 그리기
import matplotlib
matplotlib.use("Agg") # 화면 없이 파일로 (주피터에서는 생략)
import matplotlib.pyplot as plt
import numpy as np
L = "testbed/so101/cell-01/leader-arm/joint_state"
F = "testbed/so101/cell-01/follower-arm/joint_state"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[L, F],
start="2026-11-16T17:53:40+09:00", end="2026-11-16T17:54:08+09:00", purpose="analysis")
t0 = b.select(F, "gripper/position").time_ns[0]
fig, ax = plt.subplots(figsize=(10, 4))
for ch, name in [(L, "leader"), (F, "follower")]:
s = b.select(ch, "gripper/position")
ax.plot((s.time_ns - t0) / 1e9, s.values, label=name)
ax.set_xlabel("s"); ax.set_ylabel("gripper (0-100)"); ax.legend()
fig.savefig("gripper.png", dpi=120)
15.3 날짜별 녹화량 확인
from collections import defaultdict
eps = fab.events(dataset_id="plab-testbed-cell01", start="2026-11-01T00:00:00+09:00", end="2026-12-01T00:00:00+09:00",
purpose="analysis", include_unaligned=True, event_types=["episode"])["events"]
per_day = defaultdict(lambda: [0, 0.0])
for e in eps:
day = kst(e["start_ns"])[:10]
per_day[day][0] += 1
per_day[day][1] += (e["end_ns"] - e["start_ns"]) / 1e9
for day, (n, sec) in sorted(per_day.items()):
print(day, f"에피소드 {n}개, {sec / 60:.1f}분")
15.4 에피소드 하나의 손목 영상을 파일로
from pathlib import Path
ep = fab.events(dataset_id="plab-testbed-cell01", start="2026-11-16T00:00:00+09:00", end="2026-11-17T00:00:00+09:00",
purpose="analysis", include_unaligned=True, event_types=["episode"])["events"][-1]
W = "testbed/so101/cell-01/wrist-cam/image"
b = fab.read(dataset_id="plab-testbed-cell01", channels=[W], start=ep["start_ns"], end=ep["end_ns"],
purpose="analysis", link_filter={"episode_id": ep["episode_id"]})
out = Path("frames") / ep["episode_id"]
out.mkdir(parents=True, exist_ok=True)
for img in b.images[::30]: # 1초에 한 장
(out / f"{img['ts_ns']}.jpg").write_bytes(fab.content(img["content_ref"], purpose="analysis"))
print(len(list(out.glob("*.jpg"))), "장 저장:", out)
16. 메서드 요약
| 메서드 | 돌려주는 것 | 장 |
|---|---|---|
Fabric(url, *, api_key, verify, timeout, retries) |
클라이언트 | 2 |
fab.datasets(**filters) |
데이터셋 목록 (list[dict]) | 4.1 |
fab.dataset(dataset_id) |
데이터셋 상세 (dict) | 4.2 |
fab.read(*, dataset_id / snapshot_id / data_ref, start, end, channels, purpose, min_tier, include_unaligned, include_raw_times, link_keys, link_filter, link_ambiguous, format) |
Batch |
5, 6, 8 |
fab.events(*, dataset_id / snapshot_id, start, end, purpose, event_types, channels, min_tier, include_unaligned) |
{events, versions, window, excluded_count, trace_id} |
7 |
fab.latest(*, dataset_id, purpose, channels, min_tier, include_unaligned) |
{latest: {채널: {...}}} |
10 |
fab.content(content_ref, *, purpose) |
이미지 bytes | 9 |
fab.create_snapshot(*, dataset_id, start, end, channels, purpose, label) |
스냅샷 (dict) | 11 |
fab.snapshot(snapshot_id) / fab.snapshots(dataset_id) |
스냅샷 / 목록 | 11 |
fab.add_model_reference(snapshot_id, package_id, version) |
스냅샷 (dict) | 11 |
fab.export(kind, *, purpose, snapshot_id / dataset_id, start, end, channels, min_tier, include_unaligned, label) |
ExportJob |
12 |
fab.mapping(target_type, target_id) / fab.mappings_for_item(dict_item_id, include_deprecated) / fab.get_mapping(mapping_id) |
매핑 (대상 기준 / 사전 기준 / 하나) | 12-1 |
fab.register_mapping(target_type, target_id, dict_item_id, dict_version, *, replaces) / fab.deprecate_mapping(mapping_id) |
매핑 (관리 권한) | 12-1 |
fab.semantic_of(channel_id, tag) / fab.resolve_semantic(dataset_id, semantic_id, *, version, select) |
채널의 사전 항목 / 사전 항목 → 채널·tag | 12-1 |
window.Spec, window.Input, window.read(fab, spec, *, start, dataset_id / snapshot_id / data_ref), window.from_export(path, spec, *, stride_ns) |
모델 입력 텐서 (Window / Windows) |
12-2 |
Models(url, *, api_key, site_id, verify, timeout, retries) |
IF-20 클라이언트 | 12-3 |
m.infer(package_id, *, dataset_id+start / data_ref / window / inputs+data_window, version, site_id, timeout_ms, trace_id) |
Prediction (value, outputs, version, data_quality, data_window, semantic_drift, latency_ms, trace_id) |
12-3.1~3 |
m.metadata(package_id) / m.health() / m.deployments(site_id) |
입출력 형식 / 서빙 상태 / 현장 배포 | 12-3 |
m.packages(semantic_id) / m.version(package_id, version) / m.applicability(package_id, version) |
패키지 목록 / 버전 상세 / 현장 적용 가능 여부 | 12-3.4 |
m.deploy(package_id, version, *, wait) / m.job(job_id) / m.rollback(package_id, *, reason) / m.audit(trace_id) |
DeploymentJob / 작업 / 롤백 결과 / 감사 기록 |
12-3.5 |
databahn.to_ns(시각) |
datetime → int ns (문자열·int 는 그대로) | 3.4 |
17. 한도와 성능
| 항목 | 값 | 넘으면 |
|---|---|---|
| 조회 구간 | 1시간 | DAT-4002 → 나눠 조회 또는 내보내기 |
| 이벤트 조회 구간 | 31일 | DAT-4002 → 나눠 조회 |
| 스냅샷 만들기 | 제한 없음 | 읽을 때는 1시간씩 (11.2) |
| 내보내기 구간 | 제한 없음 | 크기·시간만 늘어난다 |
| 저장 데이터 양 | 관절 4채널 합쳐 1분에 약 1 MB, 카메라 2대 1분에 약 120 MB | |
| 새 데이터가 조회되기까지 | 녹화 후 최대 약 11분 (파일이 10분 단위로 닫히고, 서버가 30초마다 읽어 들인다) |
- 필요한 채널만
channels로 고르면 빠르다. 특히 카메라 채널은 관절보다 레코드가 적어도 응답이 크다. - 영상 본문(
fab.content)은 프레임마다 요청 하나다. 많이 받을 때는 필요한 프레임만 고른다(15.4 는 1초에 한 장). - 기본
format="arrow"를 유지한다. json 은 몇 배 크다.