From fd552805854dc1c5b32c5d04521ea83c6e1afbb1 Mon Sep 17 00:00:00 2001 From: gspark-etri Date: Mon, 19 Oct 2026 17:41:10 +0900 Subject: [PATCH] README: refresh in the ai-rm style, add Korean translation Centered header with badges and section nav, highlight cards, quick start with conformance output, entry-point table, protocol rules and the shared metric table in collapsible blocks, module layout, roadmap from the PROTOCOL change log. README.ko.md mirrors the English README. Co-Authored-By: Claude Opus 5.5 --- README.ko.md | 240 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 215 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 443 insertions(+), 12 deletions(-) create mode 100644 README.ko.md diff --git a/README.ko.md b/README.ko.md new file mode 100644 index 0000000..2306ff4 --- /dev/null +++ b/README.ko.md @@ -0,0 +1,240 @@ +
+ +

rm-core

+ +

ai-rm 구성요소를 잇는 계약

+ +

+ English · 한국어 +

+ +

+ CI + ai-rm 계약 + 프로토콜 v0.1 + rm-core 0.1.1 + Python 3.9+ + 런타임 의존성 없음 + 라이선스: BSD-3-Clause +

+ +

+ 빠른 시작 · + ai-rm 연동 · + 구조 · + 프로토콜 · + 로드맵 +

+ +
+ +--- + +**rm-core**는 [ai-rm](https://github.com/ai-computing/ai-rm)의 계약 패키지입니다. 가속기(L1), 메모리 계층과 KV +전송(L2), 워크로드와 배치(L3–L4), 공통 메트릭 스키마로 구성요소 사이의 약속을 정의하므로 구성요소끼리 서로 +import하지 않습니다. 타입, 인터페이스, 참조 구현, 적합성(conformance) 검사만 담고 있으며 표준 라이브러리만 쓰고 +(Python 3.9+) 런타임 의존성이 없습니다. 규범 명세는 [PROTOCOL.md](PROTOCOL.md)(v0.1, 영문)이고, 현재 릴리스는 +0.1.1입니다. + +## ✨ 주요 특징 + + + + + + + + + + + + +
+계층별 타입 계약
+Accelerator / AcceleratorProvider(L1), MemoryTier / KVLayout / +KVTransport(L2), Workload / Placement(L3–L4). 검증에 실패하면 +ContractError를 냅니다. +		 +이름으로 선택
+구성요소는 어댑터를 Python entry point로 등록하고, 런타임은 rm_core.registry.load(group, name)로 +불러옵니다. 구현을 바꾸는 일은 코드가 아니라 설정 변경입니다. +		 +적합성 검사
+python -m rm_core.conformance가 등록된 모든 구현에 계약 검사를 돌리고 PASS, SKIP(하드웨어 없음), +FAIL로 보고합니다. +
+하나의 메트릭 언어
+rm_core.metrics.METRICS가 이름, 단위, 태그(TTFT, TPOT, tok/s, 전력, MFU, KV 전송 …)를 고정합니다. +Prometheus 시계열 이름은 airm_<name>입니다. +		 +Kubernetes 표현
+AcceleratorProfile CRD(airm.ai-computing.io/v1alpha1)와 노드 레이블. +rm_core.k8s가 만들고 다시 읽습니다. +		 +참조 구현
+sim, loopback, greedy는 하드웨어 없이 동작합니다. 기대 동작을 정의하고, 실제 +어댑터를 작성할 때 본뜰 형태가 됩니다. +
+ +## 🚀 빠른 시작 + +```bash +pip install "rm-core @ git+https://github.com/ai-computing/rm-core@v0.1.1" +python -m rm_core.conformance # 등록된 모든 구현 검사 +``` + +rm-core만 설치한 상태에서는 참조 구현이 검사됩니다. + +```text +PASS airm.accelerator_providers:sim +PASS airm.kv_transports:loopback +PASS airm.placements:greedy +``` + +그룹 하나나 구현 하나만 검사하려면 `python -m rm_core.conformance [name ...]`를 씁니다. 실패한 구현이 +하나라도 있으면 0이 아닌 코드로 종료합니다. + +## 🔌 ai-rm 연동 + +구성요소는 자기 저장소 안의 작은 어댑터 모듈에서 계약을 구현하고 entry-point 그룹에 등록합니다. + +| Entry-point 그룹 | 계약 | 등록 주체 | 참조 구현 | +|---|---|:-:|---| +| `airm.accelerator_providers` | `AcceleratorProvider` | L1 (장치 탐지) | `sim` | +| `airm.kv_transports` | `KVTransport` | L2 (데이터 이동) | `loopback` | +| `airm.placements` | `Placement` | L4 (배치 정책) | `greedy` | +| `airm.workloads` | 워크로드 runner ([§5.3](PROTOCOL.md#53-workload-runners)) | L3 (서빙, 학습) | — | + +### 계약 구현하기 + +```python +# your_pkg/airm.py +from rm_core import KVTransport, TransferPlan, TransferHandle, TransferResult, TransportError + +class P2PTransport: + name = "p2p" + def supports(self, src, dst): ... + def plan(self, request_id, src, dst, src_layout, dst_layout, tokens): ... + def submit(self, plan): ... + def wait(self, handle, timeout_s): ... + def close(self): ... +``` + +```toml +# your pyproject.toml +[project.entry-points."airm.kv_transports"] +p2p = "your_pkg.airm:P2PTransport" +``` + +```bash +python -m rm_core.conformance airm.kv_transports p2p +``` + +런타임은 설정(`kvTransport: p2p`)에 있는 이름으로 구현을 고릅니다. + +```python +from rm_core import registry +transport = registry.load("airm.kv_transports", "p2p") +``` + +본뜰 참조 구현은 `rm_core.reference`(`SimAcceleratorProvider`, `LoopbackTransport`, `GreedyPlacement`)에 +있습니다. 구성요소는 rm-core를 호환 범위로 고정해 의존합니다. 예: `rm-core>=0.1,<0.2` +([§1](PROTOCOL.md#1-scope-and-versioning)). + +
+프로토콜의 주요 규칙 +
+ +- **가속기** — `id`는 `/:`이며 재시작해도 바뀌지 않습니다. `peak_tflops`는 정밀도별 dense + 최대 성능이고 `peak_source`가 있어야 합니다. 모르는 값은 0이 아니라 생략합니다. 장치가 없으면 `discover()`는 + 예외 대신 `[]`를 돌려줍니다. +- **KV 전송** — `plan()`은 입력을 검증하고 `TransportError`를 냅니다. `wait()`는 데이터가 목적지에서 보일 때만 + 반환합니다. 전송은 다른 경로로 조용히 대체하지 않습니다. 실제 장치가 필요한 전송은 `conformance_case()`를 + 구현하고, 장치가 없으면 `rm_core.conformance.NoHardware`를 내 SKIP으로 보고됩니다. +- **배치** — pool에 있는 id만 돌려주고, 결정적이며, 맞는 자리가 없으면 예외 대신 `reason`이 담긴 빈 결정을 + 돌려줍니다. +- **메트릭** — `METRICS`에 있는 양은 정확히 그 이름과 단위로 보고합니다. 태그는 `TAG_KEYS`에서 고르며, + `mfu_pct`에는 `peak_source`, `power_w`에는 `scope=card|node`가 붙습니다. +- **보안** — 계약, 프로파일, 메트릭, 로그에는 내부 주소, 자격 증명, 토큰, 키를 담지 않습니다. 사이트 값은 환경에서 + 옵니다. + +전문: [PROTOCOL.md](PROTOCOL.md). +
+ +
+공통 메트릭 (rm_core.metrics.METRICS) +
+ +| 이름 | 단위 | 의미 | +|---|---|---| +| `ttft_p50_ms` · `ttft_p90_ms` · `ttft_p99_ms` | ms | 첫 토큰까지 걸린 시간 | +| `tpot_p50_ms` · `tpot_p90_ms` · `tpot_p99_ms` | ms | 출력 토큰당 시간 | +| `e2e_p90_ms` | ms | 요청 종단 지연, p90 | +| `tok_s` | tokens/s | 초당 생성 토큰, 측정 대상 시스템 전체 | +| `req_s` | requests/s | 초당 완료 요청 | +| `power_w` | W | 측정 구간 평균 전력 (태그 `scope=card\|node`) | +| `energy_j` | J | 측정 구간 에너지 | +| `gflops_per_w` | GFLOPS/W | 전력 효율 | +| `mfu_pct` | % | 모델 FLOPs 활용률 (태그 `peak_source`) | +| `kv_transfer_ms` | ms | 요청당 KV 전달 시간 | +| `kv_transfer_gbps` | GB/s | KV 전송 대역폭 | +| `accuracy_pct` | % | 과제 정확도 (태그 `dataset`) | +| `slo_attainment_pct` | % | SLO를 만족한 요청 비율 | +| `accelerators` | count | 사용 중인 가속기 수 (태그 `vendor`/`model`) | + +Prometheus 시계열: `airm_` (`rm_core.metrics.prometheus_name`). 태그 키: `component`, `model`, +`accelerator`, `vendor`, `scope`, `peak_source`, `dataset`, `workload`, `kv_transport`, `run_id`, `commit`. +
+ +## 🏗 구조 + +```text +src/rm_core/ +├── accelerator.py # L1: Accelerator, AcceleratorProvider; 벤더·메모리·정밀도·인터커넥트 열거형 +├── memory.py # L2: MemoryTier, KVLayout, TransferPlan/Handle/Result, KVTransport +├── workload.py # L3–L4: Workload, PlacementDecision, Placement; 워크로드 종류, SLO 키 +├── metrics.py # METRICS, TAG_KEYS, Measurement, prometheus_name +├── k8s.py # AcceleratorProfile 객체와 노드 레이블; from_profile() +├── registry.py # entry-point 그룹: available(), load(), groups() +├── reference.py # sim / loopback / greedy (하드웨어 불필요) +├── conformance.py # python -m rm_core.conformance +└── errors.py # ContractError, TransportError, NoHardware +k8s/acceleratorprofile.crd.yaml # AcceleratorProfile CRD (airm.ai-computing.io/v1alpha1) +``` + +노드 데몬은 장치마다 클러스터 범위 `AcceleratorProfile`을 게시하고, 요약 노드 레이블 +`airm.ai-computing.io/.=<개수>`와 `airm.ai-computing.io/managed=true`를 답니다. `rm_core.k8s`가 둘 다 +만들고 다시 읽습니다. 프로파일에는 주소나 자격 증명을 담지 않습니다. + +## 🧪 개발 + +```bash +pip install -e . +python -m unittest discover -s tests -v +``` + +CI는 Python 3.9–3.12에서 테스트를 돌린 뒤 `python -m rm_core.conformance`와 `python tools/check_sensitive.py .`를 +실행합니다([워크플로](.github/workflows/ci.yml)). + +## 🗺 로드맵 + +- [x] 프로토콜 v0.1: 계약, `AcceleratorProfile` CRD, 참조 구현, 적합성 검사 +- [x] 0.1.1: `AcceleratorProfile`이 `extra` 유지, `python -m` 실행 시 `NoHardware`를 SKIP으로 보고, 메트릭 이전 규칙 +- [ ] 프로토콜 v0.2: 전송 계획에 `MemoryRegion`(owner, fd/offset, size)을 넣어, 장치 간 전송이 실제 버퍼를 묶고 + 하드웨어 fixture로 적합성 검사를 통과할 수 있게 함 +- [ ] 프로토콜 v0.2: 워크로드 runner 인터페이스(`airm.workloads`) 정식화 + +변경 이력: [PROTOCOL.md § Change log](PROTOCOL.md#change-log). + +## 📚 문서 + +| | | +|---|---| +| **명세** | [PROTOCOL.md](PROTOCOL.md) · [AcceleratorProfile CRD](k8s/acceleratorprofile.crd.yaml) | +| **ai-rm** | [Umbrella](https://github.com/ai-computing/ai-rm) · [인터페이스](https://github.com/ai-computing/ai-rm/blob/master/docs/interfaces.md) · [통합 안내](https://github.com/ai-computing/ai-rm/blob/master/docs/integration-guide.md) | + +## 📄 라이선스 + +[BSD-3-Clause](LICENSE). + +
ai-rm 구성요소 · ai-computing 팀 · ETRI
diff --git a/README.md b/README.md index 9953952..0b9462e 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,112 @@ -# rm-core +
-The contracts that connect [ai-rm](https://github.com/ai-computing/ai-rm) components: -accelerators (L1), memory tiers and KV transport (L2), workloads and placement (L3–L4), and the -shared metric schema. Types, interfaces, reference implementations and conformance checks only — -standard library, Python 3.9+. +

rm-core

-- **Spec**: [PROTOCOL.md](PROTOCOL.md) (v0.1) -- **Kubernetes**: [`k8s/acceleratorprofile.crd.yaml`](k8s/acceleratorprofile.crd.yaml) +

The contracts that connect ai-rm components

+ +

+ English · 한국어 +

+ +

+ CI + ai-rm contracts + Protocol v0.1 + rm-core 0.1.1 + Python 3.9+ + No runtime dependencies + License: BSD-3-Clause +

+ +

+ Quick start · + ai-rm integration · + Architecture · + Protocol · + Roadmap +

+ +
+ +--- + +**rm-core** is the contracts package of [ai-rm](https://github.com/ai-computing/ai-rm). It defines how +components talk to each other — accelerators (L1), memory tiers and KV transport (L2), workloads and placement +(L3–L4) and the shared metric schema — so that components never import each other. It holds types, interfaces, +reference implementations and conformance checks only: standard library, Python 3.9+, no runtime dependencies. +The normative specification is [PROTOCOL.md](PROTOCOL.md) (v0.1); this is release 0.1.1. + +## ✨ Highlights + + + + + + + + + + + + +
+Typed contracts per layer
+Accelerator / AcceleratorProvider (L1), MemoryTier / KVLayout / +KVTransport (L2), Workload / Placement (L3–L4), with validation that raises +ContractError. +		 +Selected by name
+Components register adapters as Python entry points and runtimes load them with +rm_core.registry.load(group, name), so switching an implementation is a configuration change. +		 +Checked by conformance
+python -m rm_core.conformance runs the contract checks for every registered implementation and reports +PASS, SKIP (no hardware) or FAIL. +
+One metric language
+rm_core.metrics.METRICS fixes names, units and tags (TTFT, TPOT, tok/s, power, MFU, KV transfer …); +Prometheus series are named airm_<name>. +		 +Kubernetes representation
+The AcceleratorProfile CRD (airm.ai-computing.io/v1alpha1) and node labels, built and read +back by rm_core.k8s. +		 +Reference implementations
+sim, loopback and greedy need no hardware. They define the expected behavior +and are the shape to copy when writing a real adapter. +
+ +## 🚀 Quick start ```bash pip install "rm-core @ git+https://github.com/ai-computing/rm-core@v0.1.1" python -m rm_core.conformance # check every registered implementation ``` -## Implementing a contract +With only rm-core installed, the reference implementations are checked: + +```text +PASS airm.accelerator_providers:sim +PASS airm.kv_transports:loopback +PASS airm.placements:greedy +``` + +Check one group or one implementation: `python -m rm_core.conformance [name ...]`. The command exits +non-zero if any implementation fails. + +## 🔌 ai-rm integration + +Components implement a contract in a small adapter module inside their own repository and register it under an +entry-point group: + +| Entry-point group | Contract | Registered by | Reference | +|---|---|:-:|---| +| `airm.accelerator_providers` | `AcceleratorProvider` | L1 (device discovery) | `sim` | +| `airm.kv_transports` | `KVTransport` | L2 (data movement) | `loopback` | +| `airm.placements` | `Placement` | L4 (placement policy) | `greedy` | +| `airm.workloads` | workload runner ([§5.3](PROTOCOL.md#53-workload-runners)) | L3 (serving, training) | — | + +### Implementing a contract ```python # your_pkg/airm.py @@ -38,14 +131,112 @@ p2p = "your_pkg.airm:P2PTransport" python -m rm_core.conformance airm.kv_transports p2p ``` -Reference implementations to copy from: `rm_core.reference` (`SimAcceleratorProvider`, -`LoopbackTransport`, `GreedyPlacement`). +Runtimes then select it by name from configuration (`kvTransport: p2p`): + +```python +from rm_core import registry +transport = registry.load("airm.kv_transports", "p2p") +``` + +Reference implementations to copy from: `rm_core.reference` (`SimAcceleratorProvider`, `LoopbackTransport`, +`GreedyPlacement`). Components depend on rm-core with a compatible pin, e.g. `rm-core>=0.1,<0.2` +([§1](PROTOCOL.md#1-scope-and-versioning)). + +
+Key rules from the protocol +
+ +- **Accelerators** — `id` is `/:`, stable across restarts. `peak_tflops` is dense peak per + precision and needs a `peak_source`; unknown values are omitted, never zero. `discover()` returns `[]` (not an + exception) when no device is present. +- **KV transport** — `plan()` validates its inputs and raises `TransportError`; `wait()` returns only when the + data is visible at the destination; a transport never silently falls back to another path. Transports that + need real devices implement `conformance_case()` and raise `rm_core.conformance.NoHardware` when they are + absent (reported as SKIP). +- **Placement** — returns only ids from the pool, is deterministic, and returns an empty decision with a + `reason` (not an exception) when nothing fits. +- **Metrics** — the quantities in `METRICS` are reported under exactly those names and units; tags come from + `TAG_KEYS`; `mfu_pct` carries `peak_source`, `power_w` carries `scope=card|node`. +- **Security** — contracts, profiles, metrics and logs never carry internal addresses, credentials, tokens or + keys; site values come from the environment. + +Full text: [PROTOCOL.md](PROTOCOL.md). +
+ +
+Shared metrics (rm_core.metrics.METRICS) +
+ +| Name | Unit | Meaning | +|---|---|---| +| `ttft_p50_ms` · `ttft_p90_ms` · `ttft_p99_ms` | ms | time to first token | +| `tpot_p50_ms` · `tpot_p90_ms` · `tpot_p99_ms` | ms | time per output token | +| `e2e_p90_ms` | ms | end-to-end request latency, p90 | +| `tok_s` | tokens/s | generated tokens per second, whole system under test | +| `req_s` | requests/s | completed requests per second | +| `power_w` | W | mean power over the measured window (tag `scope=card\|node`) | +| `energy_j` | J | energy over the measured window | +| `gflops_per_w` | GFLOPS/W | power efficiency | +| `mfu_pct` | % | model FLOPs utilization (tag `peak_source`) | +| `kv_transfer_ms` | ms | KV handoff time per request | +| `kv_transfer_gbps` | GB/s | KV transfer bandwidth | +| `accuracy_pct` | % | task accuracy (tag `dataset`) | +| `slo_attainment_pct` | % | requests meeting the SLO | +| `accelerators` | count | accelerators in use (tag `vendor`/`model`) | + +Prometheus series: `airm_` (`rm_core.metrics.prometheus_name`). Tag keys: `component`, `model`, +`accelerator`, `vendor`, `scope`, `peak_source`, `dataset`, `workload`, `kv_transport`, `run_id`, `commit`. +
+ +## 🏗 Architecture + +```text +src/rm_core/ +├── accelerator.py # L1: Accelerator, AcceleratorProvider; vendor, memory, precision, interconnect enums +├── memory.py # L2: MemoryTier, KVLayout, TransferPlan/Handle/Result, KVTransport +├── workload.py # L3–L4: Workload, PlacementDecision, Placement; workload kinds, SLO keys +├── metrics.py # METRICS, TAG_KEYS, Measurement, prometheus_name +├── k8s.py # AcceleratorProfile objects and node labels; from_profile() +├── registry.py # entry-point groups: available(), load(), groups() +├── reference.py # sim / loopback / greedy (no hardware) +├── conformance.py # python -m rm_core.conformance +└── errors.py # ContractError, TransportError, NoHardware +k8s/acceleratorprofile.crd.yaml # AcceleratorProfile CRD (airm.ai-computing.io/v1alpha1) +``` -## Development +A node daemon publishes each device as a cluster-scoped `AcceleratorProfile` plus summary node labels +`airm.ai-computing.io/.=` and `airm.ai-computing.io/managed=true`; `rm_core.k8s` builds both +and reads them back. Profiles never contain addresses or credentials. + +## 🧪 Development ```bash pip install -e . python -m unittest discover -s tests -v ``` -BSD-3-Clause. +CI runs the tests on Python 3.9–3.12, then `python -m rm_core.conformance` and `python tools/check_sensitive.py .` +([workflow](.github/workflows/ci.yml)). + +## 🗺 Roadmap + +- [x] Protocol v0.1: contracts, `AcceleratorProfile` CRD, reference implementations, conformance checks +- [x] 0.1.1: `AcceleratorProfile` keeps `extra`, `NoHardware` reported as SKIP under `python -m`, metric migration rule +- [ ] Protocol v0.2: `MemoryRegion` (owner, fd/offset, size) in transfer plans, so device-to-device transports + can bind live buffers and pass conformance with a hardware fixture +- [ ] Protocol v0.2: formalized workload-runner interface (`airm.workloads`) + +Change log: [PROTOCOL.md § Change log](PROTOCOL.md#change-log). + +## 📚 Documentation + +| | | +|---|---| +| **Specification** | [PROTOCOL.md](PROTOCOL.md) · [AcceleratorProfile CRD](k8s/acceleratorprofile.crd.yaml) | +| **ai-rm** | [Umbrella](https://github.com/ai-computing/ai-rm) · [Interfaces](https://github.com/ai-computing/ai-rm/blob/master/docs/interfaces.md) · [Integration guide](https://github.com/ai-computing/ai-rm/blob/master/docs/integration-guide.md) | + +## 📄 License + +[BSD-3-Clause](LICENSE). + +
Part of ai-rm · ai-computing team · ETRI