Technical Documentation
공장이 어떻게 동작하는지, 납품물을 어떻게 검증하시는지, 학습 파이프라인에 어떻게 연결하시는지 정리했습니다. 소개 자료가 아니라 실제로 동작하는 코드를 그대로 기술한 문서입니다.
bnic_parser · CLI bnic
GPU와 모델, 체인은 모두 선택 요소입니다. 갖춰지지 않은 경우 해당 단계만 자동으로 대체되며,
파이프라인 자체는 언제나 완주합니다. 현재 상태는 bnic doctor로 확인하실 수 있습니다.
Architecture
각 단계는 앞 단계의 해시를 이어받습니다. 중간에 변경이 생기면 최종 검증에서 드러납니다.
원본 파일 │ sha256(bytes) → asset_id ingest.py / pipeline.py ▼ 자산 레코드 ── rights 라벨 부착 ────────────────── rights.py │ 라이선스 · 권리자 · 학습허용 · 정산조건 · 검증등급 │ (미확인 → 격리, 이후 어떤 데이터셋에도 편입 불가) ▼ GPU 파싱 ─── 장면분할 · ASR · OCR · 캡션 · 임베딩 ── gpu.py asr.py vision.py textproc.py ▼ 품질·중복·PII 필터 ──────────────────────────── quality.py ▼ 샘플 풀 (= 정제유) samples.jsonl │ 각 샘플: sample_id · span · content · annotations · quality ▼ 머클 봉인 ── leaf = sha256(0x00‖sample_id‖content_hash) ─ provenance.py │ root = sha256(0x01‖min‖max) 정렬쌍 트리 ▼ 출처 NFT 발행 ── token_id = sha256(asset_id) ──────── nft.py │ 콘텐츠 해시 중복 발행은 컨트랙트가 거부 ▼ 제품 인출 ── build --product {mixed|eval|sft|multimodal|rag|pretrain} │ 같은 풀에서 인출 조건만 달리한다 (분별증류) ▼ 납품 패키지 ── data/*.jsonl · NOTICE.md · LICENSE-REPORT.csv │ provenance.jsonl · VERIFY.md · manifest.json(봉인+서명) ▼ 학습 인용 기록 ── cite → 토큰별 카운터 ↑ ─────────── ledger.py ▼ 정산 · 역추적 ── royalty / trace ────────────────── attribution.py
CLI Reference
python -m bnic_parser <command> 형태로 실행합니다.
모든 명령은 factory.json의 설정을 읽습니다.
| 명령 | 하는 일 | 주요 옵션 |
|---|---|---|
| init | 공장 작업 디렉터리와 설정 생성 | --workdir --node --network |
| doctor | GPU · 바이너리 · 모듈 · 체인 · 키 상태 점검 | - |
| chain | 발행 체인 확정. RPC에 eth_chainId를 물어 기록 |
--network --rpc --explorer --contract --show |
| parse | 스캔 → 파싱 → 라벨링 → 봉인 → NFT 발행 | --rights --operator --batch --no-mint --force --limit |
| mint | 미발행 자산 일괄 발행 | --limit |
| build | 제품군별 판매 패키지 생성 | --product --name --dsversion --media-types --languages --licenses --holders --min-quality --max-samples --noncommercial |
| verify | 데이터셋 무결성 검증 (샤드 해시 + 머클 루트) | <데이터셋 디렉터리> |
| cite | 학습 인용 기록. 정산 근거가 된다 | --dataset --model --epochs --customer --revenue --anchor |
| trace | 응답의 근거 원본 역추적 | -k --dataset --json --no-record |
| royalty | 인용 원장 → 권리자별 정산 명세 | --period --revenue --csv |
| token | 토큰 단건 조회 (출처 · 인용 이력) | <token_id> |
| revoke | 권리자 철회 반영 + 영향 데이터셋 산출 | <asset_id> --reason --by |
| stats | 공장 현황 통계 | - |
| export-web | 사이트용 JSON 스냅샷 생성 | --out |
| demo | 데모 자산으로 전 구간 1회 실행 | --out |
Integration Guide
납품 이후 세 단계면 충분합니다. 검증하시고, 학습에 투입하시고, 인용을 기록하십니다.
# 공장과 완전히 같은 코드로 재검증한다 python -m bnic_parser verify ./kr-weather-sft-1.0.0 # 출력 { "samples_declared": 128400, "samples_found": 128400, "shard_hashes_ok": true, "root_match": true, "verdict": "OK" }
한 글자라도 달라지면 MISMATCH로 표시됩니다.
공급사의 설명에 의존하지 않고 직접 확인하실 수 있습니다.
# 제품군마다 스키마가 다르다 # pretrain → {sample_id, text, provenance} # sft → {sample_id, messages, media, provenance} # rag → {sample_id, text, span, embedding_ref, provenance} import json for line in open("data/shard-0001.jsonl", encoding="utf-8"): row = json.loads(line) train_step(row["messages"]) # row["provenance"]["token_id"] 를 버리지 말 것 - # 나중에 근거를 대야 할 때 유일한 연결고리다
# 학습이 끝나면 1회 호출한다 python -m bnic_parser cite \ --dataset ./kr-weather-sft-1.0.0 \ --model our-llm-8b \ --epochs 3 \ --revenue 120000000 \ --anchor # 온체인 앵커링(선택) # 인용 횟수 = 토큰별 샘플 수 × 에폭 수
# 모델 응답의 근거를 학습 코퍼스에서 찾는다 python -m bnic_parser trace "모델이 생성한 문장" -k 5 --json # 응답 { "grounded": true, "confidence": 0.95, "evidence": [{ "source_file": "뉴스_20260901.mp4", "locator": "03:12~03:20", "rights_holder": "…", "license": "BNIC-COMM-EXCL", "token_id": "48179103509703503300…" }], "attribution_note": "근거: …" }
HTTP로 붙이려면 사이트 서버의
POST /api/trace를 그대로 사용하시거나, 같은 함수를 직접 호출하시면 됩니다.
Schema Reference
네 개의 JSON Schema가 공장 전체의 기준입니다. 파서와 컨트랙트, 사이트가 모두 이 정의를 따릅니다.
반입된 원본 자산 1건. 콘텐츠 해시, 기술 메타데이터, 권리 라벨, 머클 루트, 발행 토큰, 상태를 담습니다.
상태: ingested → parsed → labeled → minted → published / quarantined / revoked
저작권 라벨. 빌드 게이트가 직접 읽는 필드들입니다.
training_permission이 핵심이며, 계약 만료일이 지나면 자동 배제됩니다.
학습 샘플 1행. span(원본 내 위치)과
provenance(출처 토큰 + 머클 증명)가 함께 붙어 역추적을 가능하게 합니다.
제품군에 따라 출력 필드는 달라지지만 provenance는 언제나 남습니다
ERC-721 호환 토큰 메타데이터. 표준 뷰어와 호환되면서
properties.bnic 확장 필드로 권리·인용 원장을 노출합니다.
spec_version: bnic-provenance/1.0
Verification
머클 규약은 온체인과 오프체인이 정확히 같습니다. 한쪽만 변경하면 검증이 성립하지 않으므로, 수정하실 때는 양쪽을 함께 반영해 주십시오.
leaf = sha256(0x00 ‖ sample_id ‖ "|" ‖ content_hash) node = sha256(0x01 ‖ min(a,b) ‖ max(a,b))
keccak256이 아니라 sha256입니다.
컨트랙트의 verifySample도 sha256 precompile(0x02)을 씁니다.
가스도 더 저렴합니다.
JSONL은 줄바꿈을 LF로 고정해 기록합니다. 윈도우에서 CRLF로 변환되면
샤드 해시가 어긋나므로, Git 사용 시 .gitattributes로 변환을 막아 주시기 바랍니다.
FAQ
돌아갑니다. NVDEC가 없으면 CPU 디코딩으로, ASR 모델이 없으면 해당 단계를 건너뛰고,
CLIP이 없으면 지각해시 기반 대체 임베딩으로 강등됩니다.
어떤 단계가 실제로 실행되었는지는 매니페스트의 models에 기록되므로
나중에 확인할 수 있습니다. 코어(해시·머클·라벨링·빌드·원장·역추적)는 표준 라이브러리만으로 동작합니다.
가능합니다. 파서는 결정적입니다 - 같은 입력이면 어느 노드에서 돌려도
asset_id·sample_id·token_id가 동일합니다.
배치를 쪼개 여러 노드에서 돌린 뒤 원장을 합쳐도 중복이나 충돌이 발생하지 않습니다.
같은 자산으로 인식되어 재사용됩니다. asset_id가 바이트 해시에서 나오기 때문입니다.
토큰도 콘텐츠 해시에서 파생되므로 이중 발행은 컨트랙트 레벨에서 거부됩니다.
재인코딩·리사이즈된 사본은 지각해시(pHash)로, 미세 수정된 문서는 SimHash로 잡습니다.
가능합니다. RPC나 민터 키가 없으면 자동으로 dry-run으로 동작하며,
메타데이터와 토큰 ID는 온체인 모드와 완전히 동일하게 생성됩니다.
따라서 나중에 온체인으로 승격해도 이미 배포된 데이터셋의 token_id는 바뀌지 않습니다.
두 신호를 결합합니다. 어절 3-gram 역색인에 IDF 가중을 준 어휘 일치와,
CLIP 텍스트 임베딩 코사인 유사도인 의미 유사도를 0.65 : 0.35로 섞습니다.
축자 일치가 "실제로 그 자료에서 나왔다"는 더 강한 신호이므로 가중치를 더 줍니다.
대규모 운영에서는 이 자리에 FAISS나 Qdrant를 끼울 수 있고, search 인터페이스는 그대로입니다.
주민등록번호·연락처·이메일·카드·계좌·차량번호·여권번호 7종을 정규식으로 검출해 마스킹하고
pii: 플래그를 남깁니다. 이미지에서는 얼굴 검출 결과를 플래그로 남깁니다.
기본 정책(drop_pii: true)에서는 플래그가 붙은 샘플이 데이터셋에서 제외됩니다.
마스킹만 하고 편입할지는 정책으로 조정할 수 있습니다.
메타데이터와 본문 문구에서 생성 도구 흔적을 찾아 합성물 추정치를 매깁니다. 기본 상한은 0.6이며 초과 시 배제됩니다. 모델이 자기 출력을 재학습하는 붕괴(model collapse)를 막기 위한 장치입니다.