toki
b4c6550eab
- Add node store implementation for edge app - Add adapters factory for node app - Update edge and node transport layers - Update domain rules for edge and node - Add bin scripts for edge and node - Update configs and documentation - Add agent-task node_centralized_mgmt directory
128 lines
3.9 KiB
Markdown
128 lines
3.9 KiB
Markdown
# IOP Architecture
|
|
|
|
## 개요
|
|
|
|
IOP(Inference Operations Platform)는 분산 AI 모델 추론을 위한 플랫폼이다.
|
|
단일 서비스가 아니라 협력하는 여러 앱으로 구성된다.
|
|
|
|
```
|
|
Client (OpenAI SDK)
|
|
│
|
|
▼
|
|
┌─────────┐
|
|
│ edge │ OpenAI-compatible HTTP API
|
|
└────┬────┘
|
|
│ IOP TCP + Protobuf + mTLS
|
|
▼
|
|
┌──────────────────┐
|
|
│ control-plane │ 노드 등록 / 정책 / 스케줄링
|
|
└────────┬─────────┘
|
|
│
|
|
┌─────┴──────┐
|
|
▼ ▼
|
|
┌──────┐ ┌──────┐ (N개의 node)
|
|
│ node │ │ node │
|
|
└──┬───┘ └──┬───┘
|
|
│ │
|
|
┌──┴──┐ ┌──┴──┐
|
|
│mock │ │ollama│ 어댑터
|
|
│cli │ │vllm │
|
|
└─────┘ └──────┘
|
|
|
|
┌────────┐
|
|
│ worker │ 비동기 작업 처리
|
|
└────────┘
|
|
```
|
|
|
|
## 내부 통신 프로토콜
|
|
|
|
### 와이어 포맷
|
|
|
|
```
|
|
Frame: [4 bytes big-endian uint32: length] [payload]
|
|
Payload: JSON-encoded Envelope
|
|
Envelope.Payload: JSON-encoded inner message
|
|
```
|
|
|
|
**TODO**: Payload 인코딩을 protobuf로 교체 (proto/iop/runtime.proto 참고)
|
|
|
|
### 메시지 타입
|
|
|
|
| Type | 방향 | 설명 |
|
|
|------|------|------|
|
|
| `run.request` | client → node | 추론 실행 요청 |
|
|
| `run.event` | node → client | 스트리밍 이벤트 (start/delta/complete/error) |
|
|
| `heartbeat` | 양방향 | 연결 유지 (30초 간격) |
|
|
| `cancel.request` | client → node | 실행 중단 요청 |
|
|
| `register.request` | node → edge | 사전 발급 token 기반 등록 요청 |
|
|
| `register.response` | edge → node | 등록 수락 여부와 중앙 관리 node 설정 응답 |
|
|
| `error` | node → client | 에러 응답 |
|
|
|
|
### mTLS
|
|
|
|
```yaml
|
|
tls:
|
|
enabled: true
|
|
cert: certs/node.crt
|
|
key: certs/node.key
|
|
ca: certs/ca.crt
|
|
```
|
|
|
|
`tls.enabled: true`로 설정하면 RequireAndVerifyClientCert (mTLS) 모드로 동작.
|
|
|
|
## apps/node 내부 구조
|
|
|
|
```
|
|
Hexagonal Architecture
|
|
|
|
┌───────────────────────────────┐
|
|
│ node.Node │ (application core)
|
|
│ │
|
|
TCP │ transport.Handler interface │
|
|
─────────► OnRunRequest() │
|
|
client │ OnCancel() │
|
|
└───────┬───────────────────────┘
|
|
│
|
|
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
|
|
}
|
|
```
|
|
|
|
새 어댑터를 추가하려면:
|
|
1. `apps/node/internal/adapters/<name>/` 패키지 생성
|
|
2. `runtime.Adapter` 인터페이스 구현
|
|
3. `bootstrap/module.go`에서 Registry에 등록
|
|
|
|
## 라이브러리 선택
|
|
|
|
| 라이브러리 | 역할 |
|
|
|------------|------|
|
|
| `go.uber.org/fx` | 의존성 주입 |
|
|
| `go.uber.org/zap` | 구조화 로깅 |
|
|
| `github.com/spf13/cobra` | CLI |
|
|
| `github.com/spf13/viper` | 설정 파일 |
|
|
| `google.golang.org/protobuf` | Protobuf (spec용) |
|
|
| `github.com/prometheus/client_golang` | 메트릭 |
|
|
| `modernc.org/sqlite` | 실행 이력 저장 |
|
|
|
|
## 금지 사항
|
|
|
|
- gRPC (`grpc-go`) 사용 금지
|
|
- WebSocket 기본 transport 사용 금지
|
|
- Actor framework 사용 금지
|
|
- External worker pool 사용 금지
|
|
- FSM framework 사용 금지
|
|
- Plugin framework 사용 금지
|
|
- Kubernetes 의존성 금지
|