IF-03 조회 서비스 API 명세 (테스트베드)
IF-03 데이터 소비 규약 초안(2026-11-09)의 조회·스냅샷·내보내기를 HTTP 로 제공한다. 기계가 읽는 명세는
/openapi.json, 직접 호출해 보는 화면은 /docs 에 있다. 이 문서는 필드의 뜻과 규약 대응을 설명한다.
모델 추론·배포(IF-20 게이트웨이)는 10장에 있다.
1. 공통
| 항목 | 규칙 |
|---|---|
| 기본 주소 | https://if03.data-bahn.com |
| 인증 | Authorization: Bearer <토큰>. 인증 어댑터가 토큰에서 신원(sub), 현장(site_id), 권한(grants: 데이터셋 × purpose), 현장 밖 내보내기 승인(export_scope), 위임 정보(act, trace_id), 만료(exp)를 꺼낸다. 권한은 운영 커널이 정하고 조회 서비스는 집행만 한다 (규약 7.1 FacOS 토큰 합의 전까지 고정 토큰 + 정책 파일) |
| 권한 | 모든 API 가 같은 판정을 거친다: 데이터셋 × purpose → 보안 등급(restricted 는 토큰 현장 = 데이터셋 현장) → 위임 범위(구간) → 현장 밖 내보내기(internal 은 승인 필요). 권한 없는 데이터셋은 있는지도 알리지 않는다 |
| 위임 헤더 | 위임 계정(서비스 계정, can_delegate)만 X-Act-Sub: <원 요청자>, X-Trace-Id 를 실을 수 있다. 판정은 원 요청자의 권한으로 하고, 접근 기록에는 호출한 계정·원 요청자·trace_id 가 함께 남는다. 위임 계정이 아니면 헤더를 무시한다 (IF-20 → IF-03, 정의서 R9) |
| 요청 본문 | JSON (Content-Type: application/json) |
| 응답 | JSON. /v1/query 는 format: "arrow" 면 Arrow IPC 스트림 |
| 시각 | 데이터 시각은 int64 나노초 UTC(_ns). 요청 구간은 ISO 8601(시간대 필수) 또는 int64 ns. 시작 포함, 끝 제외 |
| 감사 | 모든 요청을 접근 기록에 같은 형식으로 남긴다: 시각, 소비자, 현장, 원 요청자(위임), 동작, 대상, 구간, purpose, 레코드 수, 응답 크기, 판정 결과(allow·deny·error), 오류 코드, trace_id |
| 오류 응답 | {"code": "DAT-xxxx", "message": "...", "trace_id": "..."} (6장) |
purpose 값: training, inference, display, analysis, audit, evaluation.
min_tier 값: Tier-1 ~ Tier-4, Tier-U. 기본 Tier-4.
2. 레코드
모든 레코드는 공통 필드(규약 3.2)와 모달 필드(3.3)를 갖는다.
| 공통 필드 | 형식 | 설명 |
|---|---|---|
channel_id |
string | 채널 식별자 |
seq |
uint64 | 채널 단위 번호. 같은 channel_id·seq 의 메시지는 한 번만 |
ts_ns |
int64 | 정렬 시각 (미추정이면 ts_ingest) |
aligned |
bool | 미추정이면 false |
tier |
string | Tier-1 ~ Tier-4, Tier-U |
uncertainty_ns |
int64 | null | aligned 이면 값 |
quality |
string | GOOD / UNCERTAIN / BAD |
correction_version |
int | 읽은 판본 |
modality |
string | timeseries / image / event |
raw_times |
object | include_raw_times 일 때만: ts_source_ns, ts_gateway_ns, ts_ingest_ns |
links |
object | 연결키를 요청했을 때만: {"episode_id": {"value": "...", "match": "inside" \| "ambiguous"}} |
| 모달 | 필드 |
|---|---|
| timeseries | asset_id, tag(예: gripper/position), value, unit, sampling_rate_hz — 값이 여러 개인 메시지는 tag 마다 레코드 하나 |
| image | asset_id, format, resolution, content_hash(sha256), content_ref, is_keyframe — 본문은 /v1/content |
| event | asset_id, event_id, event_type, start_ns, end_ns, inspection_result, episode_id, task, operator_id, note, ts_entry_ns |
3. 카탈로그 (규약 4.1)
GET /v1/datasets
쿼리: site_id, modality, purpose (선택). 권한 있는 데이터셋만.
{"datasets": [{"dataset_id": "plab-testbed-cell01", "site_id": "partridge-lab", "modality": ["timeseries","image","event"],
"channel_count": 7, "security_level": "internal", "allowed_purposes": ["analysis","display","training"]}]}
GET /v1/datasets/{dataset_id}
채널별 signal_type, sampling_rate_hz, expected_tier, align_method, profile_version, data_period{first_ns,last_ns},
정렬 근거 time_origin(시각 기준점), event_point(사건 시점), min_detectable_ns, latency_model{mean_ns, bound_ns, measured_at, method}(M3 지연 모델, 없으면 null),
message_count, correction_versions, 데이터 사전 항목 semantic_id·semantic_version(채널 매핑, 없으면 null)과
tag_semantic_ids{tag: {semantic_id, semantic_version}}(tag 단위 매핑, 테스트베드 확장). 데이터셋의 link_rules, schema_version, security_level, 그리고 재정렬 알림
corrections[{channels, correction_version, correction_reason, created_at, window}]. 권한이 없으면 DAT-4031 (있는지도 알리지 않음), restricted 를 현장 밖에서 보면 DAT-4032.
GET /v1/datasets/{dataset_id}/snapshots
그 데이터셋의 스냅샷 메타데이터 목록 (5장 형식).
4. 조회 (규약 4.2 ~ 4.6)
POST /v1/query — 구간 조회 · 스냅샷 조회
| 필드 | 형식 | 필수 | 설명 |
|---|---|---|---|
dataset_id |
string | M* | snapshot_id 가 없으면 필수 |
snapshot_id |
string | M* | 스냅샷 조회. 채널·구간은 스냅샷 범위 안으로 제한 |
window |
{start, end} |
M | 최대 3600초 (넘으면 DAT-4002) |
purpose |
string | M | |
channels |
string[] | 없으면 전부 | |
min_tier |
string | 기본 Tier-4 | |
include_unaligned |
bool | 기본 false | |
include_raw_times |
bool | 기본 false | |
format |
string | json(기본, 5,000 레코드씩) / arrow(100,000 레코드씩) |
|
page_token |
string | 다음 조각. 첫 요청과 같은 판본을 읽는다 | |
trace_id |
string | 호출자 추적 ID | |
link_keys |
string[] | 레코드에 연결 판정을 붙인다 | |
link_filter |
object | {"episode_id": ["..."]} 그 값에 연결된 레코드만 |
|
link_ambiguous |
string | exclude(기본) / include |
응답 (JSON):
| 필드 | 설명 |
|---|---|
records |
레코드 (ts_ns 오름차순) |
gaps |
누락 구간 [{channel_id, start_ns, end_ns, reason}]. 보간하지 않는다 |
quality_summary |
채널별 {tier: {등급: 비율}, max_uncertainty_ns, missing_ratio, excluded_count, delivery_delay{p50_ns,p95_ns}, link_excluded_count?} |
versions |
채널별 읽은 판본 |
window |
실제 적용한 구간 (데이터셋·스냅샷 범위로 잘린 것) |
trace_id |
|
next_page_token |
남은 조각이 있으면 |
snapshot_id, dataset_id |
스냅샷 조회면 |
code |
레코드가 없으면 DAT-2061 (오류 아님) |
arrow 형식: Content-Type: application/vnd.apache.arrow.stream, Arrow IPC 스트림(zstd). 레코드는 공통·모달 필드를
열로 둔 표 하나(해당 없는 열은 null, links 는 JSON 문자열). 나머지 응답 필드는 스키마 메타데이터 if03 에 JSON.
조회 원칙 (규약 2장): 시간축은 정렬 시각만 · 채널·구간별 최신 판본(재정렬본이 대체한 옛 판은 읽지 않음) · Tier-U 기본 제외 · min_tier 미달 제외(수는 품질 요약에) · 누락은 gap · seq 중복 제거.
POST /v1/events — 이벤트 조회
본문: window(최대 31일), purpose, dataset_id 또는 snapshot_id, channels(이벤트 채널만), event_types, min_tier,
include_unaligned, trace_id. 점 이벤트와, 같은 episode_id 의 START~STOP 을 묶은 구간 이벤트(event_type: "episode",
status, discarded, marks_ns, derived_from)를 돌려준다. 구간과 겹치는 에피소드는 구간 밖에서 시작했어도 포함.
응답: {events, excluded_count, versions, window, trace_id, snapshot_id?, code?}.
GET /v1/latest — 최신값 조회
쿼리: dataset_id, purpose, channels(여러 번), min_tier, include_unaligned.
응답: {"latest": {채널: {ts_ns, age_ns, correction_version, closed_until_ns, records} 또는 {ts_ns: null, reason}}, as_of_ns, trace_id}.
저장된(닫힌) 파일 기준이라 파일 단위만큼 늦다. 실시간 값은 브로커 구독(규약 6장).
GET /v1/content — 영상 본문
쿼리: ref(레코드의 content_ref), purpose. 응답: image/jpeg 바이트.
5. 스냅샷 (규약 5장)
POST /v1/snapshots (201)
본문: dataset_id, window, purpose(training / evaluation / audit), channels, label.
그때의 최신 판본 파일 목록과 sha256 을 고정한다(데이터 복사 없음). _sync 파일도 함께. 닫힌 파일만.
응답 (Table 20):
| 필드 | 설명 |
|---|---|
| snapshot_id | snap-YYYYMMDD-xxxxxxxx |
| created_at, created_by, label, purpose | |
| scope | {dataset_id, channels, window{start_ns,end_ns}} |
| items | 채널별 {channel_id, correction_version, file_count, hash_digest} (+ _sync) |
| file_count, coverage | 고정한 파일 수, 채널별 실제 덮은 범위 |
| status | active / released |
| algorithm_version | 판본 선택 방식 |
| referenced_by | [{package_id, version, retired}] |
GET /v1/snapshots/{snapshot_id}
메타데이터. 데이터셋에 어떤 purpose 든 권한이 있으면 볼 수 있다.
POST /v1/snapshots/{snapshot_id}/references
본문: package_id, version. 이 스냅샷으로 학습한 모델을 기록한다(training 권한 필요). 참조가 남아 있으면 released 로 바꿀 수 없다.
스냅샷 조회는 /v1/query, /v1/events, /v1/exports 에 snapshot_id 를 준다. 읽을 때 파일을 스냅샷에 적힌 해시로 확인한다.
6. 내보내기 (규약 4.2 Table 15, 4.6)
POST /v1/exports (202)
| 필드 | 설명 |
|---|---|
kind |
parquet(학습용, snapshot_id 필수) / mcap(재생용, 최신 또는 스냅샷) |
purpose |
|
dataset_id 또는 snapshot_id |
|
window |
스냅샷이면 생략 가능. 한도 없음 (60초 조각으로 처리) |
channels, min_tier, include_unaligned, label |
응답: {export_id, kind, status: "PENDING", request, created_at}. 만들 때 읽을 파일 목록을 고정한다.
GET /v1/exports/{export_id}
status: PENDING / RUNNING / SUCCEEDED / FAILED. 성공하면 result{files[{name,size,sha256}], records 또는 messages, quality_summary},
실패하면 error{code, message}. 작업을 만든 소비자만 볼 수 있다.
GET /v1/exports/{export_id}/files/{name}
결과 파일 내려받기. parquet: timeseries.parquet, image.parquet, event.parquet, manifest.json.
mcap: <export_id>.mcap (요청 채널·구간을 한 파일로, log_time = 정렬 시각, 영상 본문 포함).
6-1. 데이터 사전 매핑 (규약 4.7)
데이터 사전은 TTA 가 관리한다. 여기서는 채널·필드와 사전 항목을 잇는 매핑만 등록·조회한다. 사전 항목의 정의는 두지 않는다.
등록·사용 중지는 관리 권한(dict_admin)이 있는 토큰만, 조회는 인증된 누구나. 매핑은 지우지 않는다.
매핑 레코드 (Table 18-2): mapping_id, target_type, target_id, dict_item_id, dict_version, status(active·deprecated),
registered_by, valid_from. 테스트베드가 더한 필드: verification(verified·unverified·not_found — TTA 사전에서 항목을 확인했나),
replaces(이 매핑이 대체한 매핑), deprecated_at, deprecated_by.
target_type |
target_id |
예 |
|---|---|---|
channel |
채널 ID (카탈로그에 있어야 함) | testbed/so101/cell-01/follower-arm/joint_state |
field |
규약 필드 이름 (IF-03 3.2·3.3, 시간 정합 규약 시각 필드) | ts_aligned, uncertainty_ns, value |
dataset_field |
데이터셋 정의 필드 (3.1 Table 8) | security_level |
tag (테스트베드 확장) |
<채널 ID>#<tag> — 한 채널에 값이 여러 개일 때 |
…/follower-arm/joint_state#gripper/position |
POST /v1/dictionary/mappings (201, 같은 매핑이 이미 활성이면 200)
{target_type, target_id, dict_item_id, dict_version, replaces?, valid_from?} → 매핑 레코드 + created.
- 같은 대상에 활성 매핑이 있으면 replaces 에 그 mapping_id 를 줘야 교체된다(새 매핑 active, 이전 매핑 deprecated). 없거나 다르면 DAT-4093.
규약의 두 문장(Table 18-1 "이전 매핑은 deprecated 로", DAT-4093 "활성 매핑이 있으면 거부")을 함께 살린 테스트베드 방식이다 (합의 전)
- 대상·사전 항목이 없으면 DAT-4012. 사전 연동이 없으면 존재를 확인하지 않고 verification = unverified 로 등록한다
GET /v1/dictionary/mappings
- 대상 기준:
?target_type=…&target_id=…→{target_type, target_id, active, history[]}(이력은 최신 먼저) - 사전 기준:
?dict_item_id=…[&include_deprecated=true]→{dict_item_id, mappings[]}— 같은 항목을 가진 다른 설비 찾기
채널·tag 대상은 그 채널을 볼 수 있는(데이터셋 권한이 있는) 소비자에게만 보인다. 볼 수 없으면 대상 기준은 DAT-4011, 사전 기준은 목록에서 빠진다.
GET /v1/dictionary/mappings/{mapping_id} · POST /v1/dictionary/mappings/{mapping_id}/deprecate
매핑 하나 보기, 사용 중지(삭제하지 않음, 다시 해도 같은 결과). 없으면 DAT-4011.
7. 오류 코드 (규약 9장)
| 코드 | HTTP | 뜻 |
|---|---|---|
| DAT-4001 | 400 | 요청 형식 오류 (필수 필드 누락·타입 오류, 구간 역전, 잘못된 값, 위조·재사용 page_token) |
| DAT-4002 | 400 | 구간·응답 크기 한도 초과 |
| DAT-4011 | 404 | 데이터셋에 없는 채널, 권한은 있는데 카탈로그에 없는 데이터셋, 남의 내보내기 작업, 없는(또는 볼 수 없는) 매핑 |
| DAT-4012 | 400 | 미등록 사전 항목 또는 매핑 대상 (4.7) |
| DAT-4031 | 403 | 권한 없음: 토큰 없음·모름·만료, 데이터셋 × purpose 권한 없음(데이터셋이 있는지도 알리지 않음), 위임 범위 밖, 현장 밖 내보내기 승인 없음 |
| DAT-4032 | 403 | 보안 등급 제한 (restricted 를 다른 현장에서) |
| DAT-4041 | 404 | 스냅샷 없음 또는 released |
| DAT-4091 | 502 | 파일 해시 불일치 (응답 중단) |
| DAT-4093 | 409 | 같은 대상에 활성 매핑이 이미 있음 — replaces 로 새 버전 등록 (4.7) |
| DAT-5031 | 503 | 서비스 비가용 |
| DAT-5041 | 500 | 내보내기 작업 실패 (작업 상태에 표시) |
| DAT-2061 | 200 | 조건에 맞는 레코드 없음 (응답 code) |
8. 기타
| 경로 | 설명 |
|---|---|
GET /healthz |
상태와 카탈로그 자동 동기화 상태 (인증 없음) |
GET /v1/auth/whoami |
토큰의 신원·현장·scope·관리 권한 (데이터 권한은 돌려주지 않음). IF-20 이 같은 정책 파일로 인증할 때 부른다 |
GET /docs, GET /openapi.json |
대화형 API 화면, OpenAPI 명세 (인증 없음) |
GET /manual/sdk, GET /manual/api |
SDK 매뉴얼, 이 문서 (인증 없음) |
GET /sdk/ |
SDK 패키지(wheel)와 CA 인증서 (인증 없음) |
9. 호출 예
curl -s https://if03.data-bahn.com/v1/query -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -d '{
"dataset_id": "plab-testbed-cell01", "purpose": "analysis",
"channels": ["testbed/so101/cell-01/follower-arm/joint_state"],
"window": {"start": "2026-11-16T17:53:00+09:00", "end": "2026-11-16T17:54:00+09:00"},
"min_tier": "Tier-3"}'
10. IF-20 모델 실행·서빙
학습한 모델 패키지를 등록하고, 현장에 배포하고, 추론을 받는 게이트웨이다. IF-03 과 별개 서비스지만 토큰은 같다
(IF-20 이 토큰을 IF-03 의 GET /v1/auth/whoami 로 확인한다). 기계가 읽는 명세는 /if20/openapi.json, 직접 호출해 보는 화면은 /if20/docs.
파이썬은 SDK databahn.Models (SDK 매뉴얼 12-3장).
10.1 공통
| 항목 | 규칙 |
|---|---|
| 기본 주소 | https://if20.<도메인> 또는 IF-03 주소. 두 주소 모두 /if20/… 경로만 IF-20 으로 간다 |
| 인증 | Authorization: Bearer <토큰> (IF-03 과 같은 토큰). 토큰 확인은 30초 기억한다 |
| scope | 토큰에 붙는 IF-20 권한. if20.infer 추론, if20.read 패키지·배포 조회, if20.deploy 모든 현장 배포·롤백·작업·감사, if20.deploy:test 시험 현장에만 배포·롤백(작업은 자기 것만), if20.register 등록. 없으면 MDL-4031 |
| 현장 | 운영 현장과 시험 현장(테스트베드: partridge-lab, partridge-lab-test). 시험 현장은 같은 데이터셋을 읽고 배포·롤백·current/previous 만 따로다. 모르는 현장이면 MDL-4041 |
| 데이터 권한 | 참조 전달 추론은 IF-20 서빙 계정이 호출자 대신 IF-03 을 읽는다(위임, 1장 위임 헤더). 판정은 호출자의 inference 권한으로, 접근 기록에는 서빙 계정·호출자·trace_id 가 함께 남는다 |
| 현장 | 요청의 site_id, 없으면 토큰의 현장 |
| 추적 | X-Trace-Id 를 보내면 그대로 쓰고, 없으면 만든다. 응답 헤더 X-Trace-Id 와 본문 trace_id 로 돌려준다. 이 값 하나로 IF-20 감사 기록 → 모델 버전 → 학습 이력 → IF-03 접근 기록을 잇는다 |
| 멱등 | 배포·롤백은 idempotency_key 필수. 같은 키·같은 본문이면 첫 응답을 돌려주고, 같은 키·다른 본문이면 MDL-4001 |
| 오류 응답 | {"code": "MDL-xxxx", "p4_code": "INV-…/MOD-…" 또는 null, "retryable": bool, "message", "cause": "DAT-…" 또는 null, "trace_id", "detail"?} (10.7) |
10.2 추론 — POST /if20/v2/models/{package_id}/infer
현장의 current 버전으로 추론한다. …/versions/{version}/infer 는 그 버전(current 또는 previous)으로. KServe Open Inference Protocol v2 형식에
IF-20 매개변수를 더했다. 입력을 주는 방법이 둘이다.
참조 전달 — 데이터 위치만 보낸다. IF-20 이 모델의 데이터 요구(창 길이, 격자, 최저 등급, 허용 누락)대로 IF-03 에서 읽어 텐서를 만든다.
{"parameters": {"data_ref": {"if03_dataset": "plab-testbed-cell01", "window": {"start": "2026-11-18T11:10:20Z"}},
"site_id": "partridge-lab", "timeout_ms": 3000}}
| 필드 | 필수 | 설명 |
|---|---|---|
parameters.data_ref.if03_dataset |
M | IF-03 데이터셋 |
parameters.data_ref.window.start |
M | 창 시작 (ISO 8601 또는 int ns, 정렬 시각) |
parameters.data_ref.window.end |
주면 모델 창 길이와 같아야 한다 (다르면 MDL-4221). 없으면 start + 창 길이 | |
parameters.site_id |
없으면 토큰의 현장 | |
parameters.timeout_ms |
동기 제한. 기본 3000, 최대 10000. 넘으면 MDL-5040 | |
id |
호출자 요청 ID (응답에 그대로) |
입력 채널은 배포 때 데이터 사전 매핑(semantic_id)으로 풀어 고정한 것을 쓴다. 창의 누락 비율이 허용을 넘거나 최저 등급이 모자라면
MDL-4221 (detail.data_quality 에 실제 값). 호출자에게 그 데이터셋의 inference 권한이 없으면 MDL-4031 (cause: DAT-4031).
값 전달 — 호출자가 만든 텐서를 보낸다. 그 텐서를 만든 창 구간과 시간축을 함께 적어야 한다.
{"inputs": [{"name": "state", "datatype": "FP32", "shape": [1, 30, 6], "data": [94.6, …, null, …]}],
"parameters": {"data_window": {"start_ns": 1795432220000000000, "end_ns": 1795432221000000000},
"time_basis": "aligned"}}
| 필드 | 필수 | 설명 |
|---|---|---|
inputs[] |
M | 모델 입력 전부. name, datatype(FP32), shape(모델 shape 와 맞아야, -1 은 아무 값), data(평탄화, 값 없는 칸은 null) |
parameters.data_window |
M | 이 텐서를 만든 창 구간. 응답에 그대로 돌려준다 |
parameters.time_basis |
M | "aligned" (IF-03 정렬 시각으로 만든 텐서) |
이름·datatype·shape·값 개수가 맞지 않으면 MDL-4221.
응답 (두 방법 공통)
{"model_name": "so101-tracking-baseline", "model_version": "0.1.0", "id": null,
"outputs": [{"name": "anomaly_score", "datatype": "FP32", "shape": [1, 1], "data": [2.2844]}],
"parameters": {"model_ref": {"package_id": "so101-tracking-baseline", "version": "0.1.0"},
"data_window": {"start_ns": …, "end_ns": …, "if03_dataset": "plab-testbed-cell01", "time_basis": "aligned"},
"latency_ms": 122.4, "trace_id": "tr-…", "site_id": "partridge-lab",
"data_versions": {"<채널>": [1]},
"data_quality": {"tier": {"Tier-3": 1.0}, "min_tier": "Tier-3", "missing_ratio": {"state": 0.0, "command": 0.0}},
"semantic_resolution": {"state": {"channel": "<채널>",
"mappings": [{"mapping_id", "dict_version", "channel_id", "tag"}]}}}}
data_versions, data_quality, semantic_resolution 은 참조 전달일 때만 (값 전달은 데이터를 IF-20 이 보지 않았다).
semantic_drift (참조 전달이고 배포 데이터셋일 때, 비면 []): 배포 때 고정한 입력 매핑 중 그 뒤 사용 중지된 것.
[{input, mapping_id, target_type, target_id, dict_item_id, dict_version, status: "deprecated", deprecated_at, replacement}],
replacement 는 같은 대상의 지금 활성 매핑 {mapping_id, dict_item_id, dict_version} (없으면 null).
매핑이 바뀌어도 배포된 모델의 입력은 말없이 바뀌지 않는다 — 고정한 채널로 계속 추론하고 알리기만 한다. 다시 배포하면 지금 매핑으로 다시 푼다.
처음 발견하면 감사 기록(semantic_drift)을 한 번 남기고 헬스체크에 표시한다. 매핑 상태는 60초 기억한다(사용 중지는 계속).
latency_ms 는 IF-20 이 요청을 받아 응답을 만들기까지.
10.3 모델 정보·헬스체크
| 경로 | scope | 설명 |
|---|---|---|
GET /if20/v2/models/{package_id}?site_id= |
read | OIP 메타데이터: 입력·출력 이름·datatype·shape, parameters.deployments[{site_id, version, role}] |
GET /if20/health |
없음 | {"status": "UP"\|"DEGRADED"\|"DOWN", "endpoints": [{site_id, package_id, status, current: {version, ready, semantic_drift: [mapping_id…]}, previous}]}. semantic_drift 는 추론 때 발견한 사용 중지 매핑 (상태값은 바꾸지 않는다 — 서빙은 정상). 현장·패키지마다 current 와 previous 가 모두 준비되면 UP, current 만이면 DEGRADED, current 가 준비 안 되면 DOWN. 전체는 가장 나쁜 것 |
GET /if20/healthz |
없음 | 프로세스 생존 (ALB·kubelet) |
10.4 패키지 레지스트리
| 경로 | scope | 설명 |
|---|---|---|
POST /if20/v1/packages (201) |
register | 등록. 본문 {package_id, version(semver), run_id, artifact_path?("model"), artifact_sha256?{"model.onnx", "manifest.json"}}. 학습 run 에 snapshot_id·data_selection 이 없으면 MDL-4222, manifest 규칙 위반은 MDL-4001, 같은 버전이 이미 있으면 409 MDL-4001, 해시가 다르면 MDL-4091. 통과하면 IF-20 이 서명하고 lifecycle Draft 로 둔다. 응답 {package_id, version, lifecycle, training_ref{job_id, snapshot_id}, signature{algorithm, key_id, files}, trace_id} |
GET /if20/v1/packages?semantic_id= |
read | 버전 목록 [{package_id, version, semantic_ids, lifecycle, owner}]. semantic_id 를 주면 그 사전 항목을 입력으로 쓰는 것만 |
GET /if20/v1/packages/{id}/versions/{v} |
read | manifest(training_ref, signature 포함), training_history{job_id, image, snapshot_id, data_selection, params, metrics, resources_used}, deployments{현장: 역할} |
GET /if20/v1/packages/{id}/versions/{v}/applicability?site_id=&if03_dataset= |
read | 그 현장(데이터셋)에서 입력을 풀 수 있는지: {applicable, site_allowed, inputs{입력: {status: ok\|none\|ambiguous, channel, …}}}. 배포 전에 확인 |
manifest 규칙(등록 때 검사): format: "standard", runtime.framework: "onnx", 입출력 dtype float32, data_requirements 의 격자·창 길이,
sites(배포 가능 현장), resources{gpu, memory_mb}.
10.5 배포·롤백
| 경로 | scope | 설명 |
|---|---|---|
POST /if20/v1/deployments (202) |
deploy · deploy:test(시험 현장) | 본문 {model_ref{package_id, version}, site_id, strategy: "replace", module_id?, idempotency_key} (키는 헤더 Idempotency-Key 로도). 응답 {job_id, status: "QUEUED", trace_id} |
GET /if20/v1/jobs/{job_id} |
deploy · deploy:test(자기 작업) | {job_id, kind, status: QUEUED\|RUNNING\|SUCCEEDED\|FAILED\|CANCELLED, request, result, error{code, message, …}, requester, trace_id, created_at, started_at, finished_at, heartbeat_at} |
POST /if20/v1/rollbacks |
deploy · deploy:test(시험 현장) | 본문 {package_id, site_id, reason, idempotency_key}. 응답 {site_id, package_id, current, rolled_back, trace_id}. previous 가 없으면 MDL-4042(P4 INV-4041) |
GET /if20/v1/sites/{site_id}/deployments?all= |
read | 현장 배포 [{package_id, version, role, isvc, job_id, reason, if03_dataset, created_at, updated_at}]. all=true 면 은퇴·실패까지 |
배포 작업 순서: 서명 확인(다르면 MDL-4091) → 자원 확인(GPU 요구·메모리 4096 MB 초과면 MDL-5071) → 입력 semantic_id 를 현장 데이터셋에서
풀어 고정(없거나 여럿이면 MDL-4223) → 모델 저장소 기록 → 서빙 생성 → Ready 대기(시간 초과 MDL-5031, 새 서빙만 지우고 기존 current 유지)
→ 0 입력 시험 추론 → 교체. 교체하면 current → previous, 그 전 previous 는 은퇴(서빙 삭제). 현장·패키지마다 서빙은 최대 2개.
이미 current 인 버전을 다시 배포하면 바로 SUCCEEDED (result.note: "이미 current").
성공한 작업의 result: {site_id, model_ref, endpoint, isvc, initial_metrics{test_latency_ms}, allocated{gpu, memory_mb, cpu}, retired[],
resolved_inputs{입력: {channel, mappings}}}.
롤백은 previous 를 current 로 올리고, 롤백된 버전은 은퇴한다 (previous 가 되지 않는다 — 롤백 뒤 헬스체크는 DEGRADED).
10.6 감사
GET /if20/v1/audit?trace_id= (scope deploy): 그 trace_id 의 IF-20 기록
[{ts, trace_id, event, sub, act, site_id, package_id, version, result, detail}].
event: register, deploy, rollback, infer, signature_failed, resource_denied, semantic_drift. result: ok / fail / warn(semantic_drift).
10.7 오류 코드
| 코드 | HTTP | P4 코드 | 다시 시도 | 뜻 |
|---|---|---|---|---|
| MDL-4001 | 400 (중복 등록 409) | 요청 형식 오류, manifest 규칙 위반, 같은 버전 재등록, 같은 멱등 키에 다른 본문 | ||
| MDL-4031 | 403 | 토큰 없음·모름, scope 없음, deploy:test 로 운영 현장 배포·롤백, 참조 전달에서 호출자의 데이터 권한 없음(cause: DAT-4031/4032) |
||
| MDL-4041 | 404 | 패키지·버전·작업·현장 없음 | ||
| MDL-4042 | 404 | INV-4041 | 현장에 배포된 버전 없음, 롤백할 previous 없음 | |
| MDL-4091 | 409 | 아티팩트 해시·서명 불일치 (등록 때 또는 배포 때) | ||
| MDL-4221 | 422 | 입력이 모델에 맞지 않음: 값 전달의 이름·shape·datatype, 참조 전달의 창 길이·누락 비율·최저 등급 | ||
| MDL-4222 | 422 | 학습 이력(run, snapshot_id, data_selection) 없음 | ||
| MDL-4223 | 422 | 입력 semantic_id 를 현장 데이터셋에서 풀 수 없음 (대응 없음 또는 여럿) | ||
| MDL-5000 | 500 | 내부 오류 | ||
| MDL-5031 | 503 | MOD-5031 | 예 | 서빙 준비 안 됨, IF-03·레지스트리 비가용 |
| MDL-5040 | 504 | INV-5040 | 예 | 동기 제한 초과 |
| MDL-5071 | 507 | MOD-5071 | 예 | 서빙 자원 부족 (GPU 요구, 메모리 한도 초과) |
10.8 호출 예
curl -s https://if20.<도메인>/if20/v2/models/so101-tracking-baseline/infer \
-H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H 'X-Trace-Id: tr-my-first-infer' -d '{
"parameters": {"data_ref": {"if03_dataset": "plab-testbed-cell01", "window": {"start": "2026-11-18T11:10:20Z"}}}}'