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

채널·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"}}}}'