toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/README.md
toki 6e2a1fc2f2 feat: edge runtime, opsconsole, CLI target terminology, and e2e validation updates 
- Add edge runtime config and opsconsole package
- Refactor edge console to use new runtime config
- Add service source metadata support
- Update CLI adapter with target terminology
- Add edge operation contract and event bus replay
- Update node label and command ops surface
- Add E2E smoke tests and full validation
- Update proto runtime definitions
- Update documentation and agent-ops rules
2026-05-17 14:57:49 +09:00

276 lines
12 KiB
Markdown
Raw Blame History

# IOP
IOP(Inference Operations Platform)는 단순한 모델 라우터나 OpenAI API proxy가 아니다.
IOP는 **Control Plane - Edge - Node** 계층 구조를 기반으로, 여러 로컬 모델 런타임과 CLI Agent 실행 환경을 통합 관리하는 실행 오케스트레이션 플랫폼을 지향한다. 모델 서빙, CLI Agent 실행, shell/git/docker/code workspace 작업, node maintenance 작업을 같은 실행 파이프라인에서 다룰 수 있도록 만드는 것이 핵심 방향이다.
현재 프로젝트는 완성된 운영 시스템이 아니라 스켈레톤 단계다. 이 README는 현재 구현의 세부 사용법보다, 프로젝트가 향하는 구조와 경계를 명확히 설명한다.
## Overview
IOP의 실행 대상은 크게 두 가지다.
- **Model Serving**
- Ollama
- vLLM
- MLX
- 그 외 로컬/원격 모델 런타임
- **Agent / Automation Execution**
- CLI Agent
- Shell
- Git
- Docker
- Code workspace 작업
- NomadCode 계열 자동화 작업
IOP는 model serving만 담당하는 시스템이 아니다. CLI Agent 실행과 node maintenance도 adapter 기반 실행으로 보고, Edge와 Node를 통해 실행 요청, 스트림, 상태, 결과를 관리하는 방향으로 설계한다.
## Core Concept
IOP의 중심 개념은 `adapter + target` 기반 실행이다.
- `adapter`는 실행 방식을 나타낸다.
- `target`은 해당 adapter 안에서 실행할 구체 대상을 나타낸다.
- `execution`은 adapter와 target을 해석해 실제 Node에서 수행되는 단위다.
예시는 다음과 같다.
```text
adapter = ollama
target = qwen3.6
adapter = vllm
target = gemma4
adapter = cli
target = cline-dgx
adapter = cli
target = codex-local
```
외부 OpenAI API 호환 계층에서는 호환성을 위해 `model` 필드가 남을 수 있다. 그러나 내부 실행 개념에서는 모델 이름만으로 전체 실행을 설명하지 않고, `adapter`, `target`, `execution`, `node adapter`, `adapter execution` 같은 용어를 우선한다.
## Architecture
IOP는 Control Plane이 Edge를 통해 시스템을 제어하고, Edge가 자신의 로컬 실행 그룹을 운영하는 구조를 지향한다.
```text
Control Plane
├─ Edge Group A
│ ├─ Node 1
│ ├─ Node 2
│ └─ Node 3
└─ Edge Group B
├─ Node 4
└─ Node 5
```
Control Plane은 Node에 직접 연결하지 않는다. 전체 시스템 제어는 Edge를 통해 이뤄지고, Edge는 자신이 관리하는 Node와 로컬 런타임 상태의 원본을 가진다.
핵심 문장은 다음과 같다.
> Control Plane은 Edge를 통해 시스템을 제어하고, Edge는 자신의 로컬 런타임 상태를 소유하고 운영한다.
### Control Plane
Control Plane은 자체 서버와 프론트 페이지를 가진 중앙 관리 계층이다.
주요 책임은 다음과 같다.
- 여러 Edge 연결 관리
- Edge 상태 조회
- Edge 설정 변경
- Edge에 명령 전달
- Edge 이벤트 수신
- 전체 시스템 관찰
- Runtime 영역과 Automation 영역을 나눠 보여주는 운영 화면 제공
Control Plane과 Edge는 소켓 기반 연결을 사용하고, 이벤트, 상태, 명령 결과를 실시간으로 주고받는 구조를 지향한다.
Control Plane은 전통적인 Kubernetes식 중앙 스케줄러가 아니다. 다음 책임은 Control Plane에 두지 않는다.
- Node 직접 연결
- Node 직접 스케줄링
- Edge 내부 DB 대체
- 모든 런타임 상태의 단일 원본화
- 매 요청마다 Node 할당 판단
### Edge
Edge는 단순 API gateway가 아니라 백엔드 전용 실행 그룹 컨트롤러다.
하나의 Edge는 여러 Node를 관리하며, 특정 디바이스 그룹, 로컬 모델 그룹, 자동화 실행 그룹을 하나로 묶는 단위가 된다. Edge는 모델 서빙과 CLI Agent 실행을 모두 처리할 수 있어야 한다.
Edge의 핵심 역할은 다음과 같다.
- Node registry
- Node configuration
- Adapter/Profile configuration
- Runtime routing
- Edge service API surface
- Job assignment
- Stream relay
- Session handling
- Local runtime state
- Execution history aggregation
- Event aggregation
Edge는 자신의 데이터를 자체적으로 가진다. Control Plane은 Edge의 데이터를 조회하고 조정하지만, 런타임 데이터의 원본은 Edge다.
현재 edge 내에는 edge-local ops console이 있다. ops console의 `/` 명령은 `apps/edge/internal/service`를 호출하는 얇은 어댑터이며, 향후 HTTP/API handler도 같은 service를 호출하는 방향이다. HTTP/API를 central/remote management surface로, ops console을 edge-local diagnostic surface로 구분한다. 실행 이벤트와 node lifecycle 이벤트는 `apps/edge/internal/events` bus를 통해 fanout한다.
### Node
Node는 실제 실행자다.
Node는 모델 런타임, CLI Agent, 도구 실행을 담당한다. Node는 Control Plane이 아니라 Edge에 연결되며, Edge가 전달한 실행 요청을 adapter execution으로 수행하고 이벤트와 결과를 되돌려준다.
Node는 가능한 한 단순한 실행 단위로 유지한다. 정책, 전체 시스템 조정, 다중 Edge 운영 판단을 Node에 밀어 넣지 않고, 전달받은 실행을 안정적으로 수행하는 데 집중한다.
### Worker Structure
Edge, Node, Control Plane은 별도 `iop-worker` 앱으로 분리하지 않고, 각 Go 서비스 내부의 공통 Worker 모듈을 사용한다. 공통 처리 모델은 `Job Queue`, `Worker Pool`, `Job Status`, `Retry`, `Timeout`, `Cancel`이며, Worker가 담당하는 역할은 서비스별 책임에 맞춰 분리한다.
- **Edge Worker**
- 사용자 요청 처리 흐름에 붙는 짧은 병렬/비동기 작업을 담당한다.
- intent 분석, history refinement, routing 보조, 응답 validation, fallback 판단, stream 종료 후 usage/log/metric 기록을 처리한다.
- **Node Worker**
- 모델 런타임과 로컬 프로세스에 붙는 작업을 담당한다.
- runtime adapter 처리, model process 상태 감시, local queue 처리, streaming relay 보조, local metric/log flush를 처리한다.
- **Control Plane Worker**
- 운영/관리/스케줄 기반 작업을 담당한다.
- node health 수집, model registry 동기화, policy/config 배포, drain/reload 명령, benchmark/job 실행, 운영 리포트와 cleanup 작업을 처리한다.
## Execution Model
### Adapter and Target
IOP 내부 실행은 model 중심이 아니라 adapter 중심으로 정리한다.
- `adapter`: `mock`, `ollama`, `vllm`, `cli` 같은 실행 구현
- `target`: adapter 안에서 선택되는 모델, profile, agent, toolchain
- `execution`: 특정 adapter와 target으로 수행되는 단일 실행
- `node adapter`: Node 안에 등록되어 실제 실행을 담당하는 adapter
- `adapter execution`: Node adapter가 수행하는 실행 단위
현재 코드에는 `RunRequest`, `ExecutionSpec`, `RuntimeEvent`, `NodeCommandRequest`, `EdgeNodeEvent`처럼 이 방향을 담기 위한 타입들이 있다. `RunEvent`는 adapter execution stream에, `EdgeNodeEvent`는 node 연결/해제 같은 edge-node lifecycle과 이후 제어/상태성 이벤트에 사용한다. 세부 계약과 schema는 작업을 진행하면서 점진적으로 정리한다.
### Runtime Domain
Runtime Domain은 모델 서빙 중심 실행 영역이다.
- OpenAI API 호환 요청
- Ollama, vLLM, MLX 같은 모델 런타임
- 모델 라우팅
- 추론 요청 처리
- 모델 런타임 adapter 확장
이 영역에서도 내부적으로는 `adapter + target` 개념을 사용한다. 예를 들어 OpenAI 호환 요청의 `model` 값은 내부에서 특정 adapter와 target으로 해석될 수 있다.
### Automation Domain
Automation Domain은 CLI Agent와 도구 실행 중심 영역이다.
- CLI Agent 실행
- Shell, Git, Docker 작업
- code workspace 작업
- Plane 작업과 유지보수 작업
- Claude CLI, Gemini CLI, Codex CLI, OpenCode, Cline 같은 실행 대상
NomadCode는 IOP 안에 완전히 흡수된 제품이 아니라, IOP Automation Domain 위에서 동작할 수 있는 대표 사용처로 본다.
```text
IOP Core
└─ 공통 실행 오케스트레이션 계층
NomadCode
└─ IOP Automation Domain을 활용하는 개발 업무 자동화 도메인
```
## Current Status
현재 go-iop는 스켈레톤 단계다.
- Edge-Node 소켓 기반 구조를 우선 검증 중이다.
- Node 등록, 설정 전달, 실행 요청, 스트리밍 이벤트 흐름이 점진적으로 정리되고 있다.
- Edge 내부에는 API 전환을 고려한 `apps/edge/internal/service`와 in-process event fanout인 `apps/edge/internal/events`가 있다.
- cli adapter(node execution implementation) 쪽 구현이 먼저 진행되고 있다.
- edge-local ops console의 `/` 명령은 수동 테스트 표면이며, 장기 인터페이스는 별도 HTTP/API 표면으로 추가한다.
- 현재 실행 이력은 Node local SQLite store에서 검증 중이다. Edge 단위 이력 집계와 로컬 실행 그룹 상태 소유권은 로드맵에 따라 정리한다.
- `mock` adapter와 dummy/TODO 구현은 개발 단계에서 정상적인 구성이다.
- Ollama/vLLM 등 모델 runtime adapter는 단계적으로 확장한다.
- Control Plane은 향후 여러 Edge 관리와 프론트 페이지 제공을 위해 추가된다.
현재 앱 구성은 다음과 같다.
| 경로 | 현재 의미 |
|---|---|
| `apps/node` | Edge에 연결되어 adapter execution을 수행하는 Node agent |
| `apps/edge` | Node registry, 설정 전달, routing, stream relay를 담당하는 Edge skeleton |
| `apps/control-plane` | 향후 여러 Edge를 연결하고 운영 화면을 제공할 중앙 관리 계층 |
| `apps/worker` | 현재 placeholder이며, Worker 구조는 우선 각 Go 서비스 내부 공통 모듈 방향으로 둔다 |
| `packages` | 설정, 인증, 정책, 작업, 관측성, 버전 등 공통 패키지 |
| `proto` | 앱 간 메시지 계약 원본과 생성물 |
| `configs` | 현재 개발용 설정 예시 |
## Roadmap
### Phase 1. Edge-Node execution skeleton
- Edge-Node 소켓 연결
- Node adapter execution
- CLI adapter 검증
- `adapter + target` 개념 정리
### Phase 2. Runtime and Automation unification
- 모델 서빙 adapter 확장
- CLI Agent 실행 안정화
- Runtime / Automation 실행 흐름 공통화
- Node local execution history와 Edge event aggregation 경계 정리
### Phase 3. Control Plane
- 자체 서버와 프론트 페이지 제공
- 여러 Edge 연결
- Edge 상태 조회
- Edge 설정 변경
- Edge 명령 전달
- 이벤트 수신
### Phase 4. Multi-Edge operations
- 여러 Edge group 관리
- Edge별 runtime/automation 상태 표시
- Edge 단위 실행 이력과 상태 집계
- Edge 단위 작업 실행과 제어
### Phase 5. Policy, History, Audit
- 권한, 정책, 이력, 감사 기능 확장
- 상세 설계는 후속 작업에서 결정
## Development Notes
- 기존 구조를 우선하며, 세부 구현은 각 작업의 domain rule과 현재 코드 경계를 먼저 확인한 뒤 진행한다.
- 내부 통신은 TCP/protobuf 기반 소켓 흐름을 우선한다.
- gRPC 도입, WebSocket 기본 transport 전환, actor/FSM/plugin framework 도입은 현재 단계의 기본 방향이 아니다.
- OpenAI API 호환 계층은 외부 호환을 위한 표면이며, 내부 실행 모델 전체를 대표하지 않는다.
- 앱별 README에는 현재 수동 테스트나 구현 세부가 더 많이 남아 있을 수 있다. 루트 README는 전체 방향과 경계를 설명하는 문서로 유지한다.
## Non-Goals for Current Stage
이번 단계에서는 다음 내용을 루트 README에서 상세 설계로 확정하지 않는다.
- 상세 DB schema
- 상세 protobuf 설계
- 상세 event schema
- 상세 permission model
- 상세 policy engine 설계
- 상세 audit log 구조
- Edge federation 세부 설계
- mTLS 세부 구현 계획
- Control Plane UI 화면별 상세 기획
- Plane 연동 상세 workflow
- NomadCode 상세 제품 설계
Reference in a new issue View git blame Copy permalink