toki
6e2a1fc2f2
- 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
125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# IOP Architecture
|
|
|
|
## 개요
|
|
|
|
IOP(Inference Operations Platform)는 모델 서빙과 CLI Agent/Automation 실행을 함께 다루는 실행 오케스트레이션 플랫폼을 지향한다. 단순한 OpenAI-compatible proxy나 모델 라우터가 아니라, Control Plane - Edge - Node 계층으로 로컬 실행 그룹을 관리하는 구조를 목표로 한다.
|
|
|
|
현재 구현은 Edge-Node 실행 스켈레톤을 검증하는 단계다. Control Plane과 worker는 placeholder이며, 세부 계약은 후속 작업에서 정리한다.
|
|
|
|
## 계층 구조
|
|
|
|
```text
|
|
Control Plane
|
|
├─ Edge Group A
|
|
│ ├─ Node 1
|
|
│ │ ├─ adapter: cli
|
|
│ │ └─ adapter: ollama
|
|
│ └─ Node 2
|
|
│ └─ adapter: vllm
|
|
└─ Edge Group B
|
|
└─ Node 3
|
|
└─ adapter: cli
|
|
```
|
|
|
|
Control Plane은 Node에 직접 연결하지 않는다. Control Plane은 Edge 연결을 관리하고, Edge 상태를 조회하고, Edge 설정을 조정하고, Edge에 명령을 전달하는 중앙 관리 계층이다.
|
|
|
|
Edge는 여러 Node를 묶는 실행 그룹 컨트롤러다. Edge는 Node registry, adapter/profile configuration, routing, stream relay, session handling, event aggregation을 담당한다.
|
|
|
|
Node는 실제 실행자다. Node는 Edge에 연결되어 adapter execution을 수행하고, RuntimeEvent를 Edge로 돌려준다. 연결 생명주기와 이후 제어/상태성 이벤트는 RunEvent와 분리된 EdgeNodeEvent envelope로 다룬다.
|
|
|
|
## 현재 Edge-Node 흐름
|
|
|
|
현재 검증 중인 기본 흐름은 다음과 같다.
|
|
|
|
```text
|
|
Edge
|
|
└─ accepts Node connection
|
|
└─ validates token
|
|
└─ sends NodeConfigPayload
|
|
└─ relays RunRequest / NodeCommandRequest
|
|
|
|
Node
|
|
└─ receives adapter/runtime config
|
|
└─ builds adapter registry
|
|
└─ resolves adapter + target
|
|
└─ executes adapter
|
|
└─ emits RuntimeEvent / EdgeNodeEvent
|
|
```
|
|
|
|
현재 실행 이력은 Node의 local SQLite store에서 검증 중이다. Edge 단위 이력 집계와 로컬 실행 그룹 상태 소유권은 로드맵에 따라 정리한다.
|
|
|
|
edge-local ops console의 `/` 명령은 ops console의 수동 테스트 표면이다. ops console은 `edge/internal/service`를 호출하는 얇은 어댑터로 유지하고, 이후 HTTP/API 표면(central/remote management surface)도 같은 service와 `edge/internal/events` bus를 재사용한다.
|
|
|
|
ops console과 HTTP/API를 구분한다: ops console은 edge-local diagnostic surface이고, HTTP/API는 central/remote management surface다.
|
|
|
|
## 내부 실행 모델
|
|
|
|
내부 실행은 `adapter + target`으로 표현한다.
|
|
|
|
- `adapter`: 실행 방식. 예: `mock`, `ollama`, `vllm`, `cli`
|
|
- `target`: adapter 안의 실행 대상. 예: 모델 이름, CLI profile, agent/toolchain
|
|
- `execution`: 특정 adapter와 target으로 수행되는 단일 실행
|
|
|
|
외부 OpenAI-compatible API에서는 호환성을 위해 `model` 필드가 남을 수 있다. 그러나 내부 실행 계약에서는 `target`을 우선한다.
|
|
|
|
## apps/node 내부 구조
|
|
|
|
```text
|
|
Hexagonal Architecture
|
|
|
|
┌───────────────────────────────┐
|
|
│ node.Node │ application core
|
|
│ │
|
|
TCP │ transport.Handler interface │
|
|
─────────► OnRunRequest() │
|
|
edge │ OnCancel() │
|
|
│ OnCommandRequest() │
|
|
└───────┬───────────────────────┘
|
|
│
|
|
router.Resolve() -> ExecutionSpec
|
|
│
|
|
adapter.Execute() -> RuntimeEvent stream
|
|
│
|
|
store.CompleteRun() -> SQLite
|
|
```
|
|
|
|
### 어댑터 패턴
|
|
|
|
```go
|
|
type Adapter interface {
|
|
Name() string
|
|
Capabilities(ctx) (Capabilities, error)
|
|
Execute(ctx, spec ExecutionSpec, sink EventSink) error
|
|
}
|
|
```
|
|
|
|
새 어댑터를 추가할 때는 `runtime.Adapter`를 구현하고 registry에 등록한다. CLI Agent, 모델 런타임, 도구 실행은 모두 같은 adapter execution 경로로 다루는 방향을 유지한다.
|
|
|
|
## 통신 방향
|
|
|
|
- Edge-Node 내부 통신은 TCP + protobuf 기반 소켓 흐름을 우선한다.
|
|
- Node는 Edge에 연결한다.
|
|
- Control Plane은 향후 Edge와 소켓 기반 연결을 맺는다.
|
|
- Control Plane이 Node에 직접 연결하거나 매 요청마다 Node를 직접 스케줄링하는 구조는 목표가 아니다.
|
|
|
|
## 라이브러리 선택
|
|
|
|
| 라이브러리 | 역할 |
|
|
|------------|------|
|
|
| `go.uber.org/fx` | 의존성 주입 |
|
|
| `go.uber.org/zap` | 구조화 로깅 |
|
|
| `github.com/spf13/cobra` | CLI |
|
|
| `github.com/spf13/viper` | 설정 파일 |
|
|
| `google.golang.org/protobuf` | Protobuf |
|
|
| `github.com/prometheus/client_golang` | 메트릭 |
|
|
| `modernc.org/sqlite` | 현재 Node local 실행 이력 저장 |
|
|
|
|
## 금지 사항
|
|
|
|
- gRPC (`grpc-go`) 사용 금지
|
|
- WebSocket 기본 transport 사용 금지
|
|
- Actor framework 사용 금지
|
|
- External worker pool 사용 금지
|
|
- FSM framework 사용 금지
|
|
- Plugin framework 사용 금지
|
|
- Kubernetes 의존성 금지
|