toki/iop

toki 2d6fde0876 기능: IOP 모노레포 스캐폴드 초기 구현

apps/node 중심 구현 — TCP+JSON transport, Hexagonal Architecture,
mock/cli adapter, fx DI, SQLite 실행 이력 저장.
edge/control-plane/worker는 cobra placeholder.
유닛 테스트 및 통합 테스트 클라이언트 계획서 추가.

2026-05-02 13:20:35 +09:00

3.9 KiB

Raw Blame History

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	실행 중단 요청
`capability.request`	client → node	어댑터 목록 요청
`capability.response`	node → client	어댑터 정보 응답
`error`	node → client	에러 응답

mTLS

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 │  OnCapabilityRequest()        │
         │  OnCancel()                   │
         └───────┬───────────────────────┘
                 │
          router.Resolve()     → ExecutionSpec
                 │
          adapter.Execute()    → RuntimeEvent stream
                 │
          store.CompleteRun()  → SQLite

어댑터 패턴

type Adapter interface {
    Name() string
    Capabilities(ctx) (Capabilities, error)
    Execute(ctx, spec ExecutionSpec, sink EventSink) error
}

새 어댑터를 추가하려면:

apps/node/internal/adapters/<name>/ 패키지 생성
runtime.Adapter 인터페이스 구현
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 의존성 금지

3.9 KiB Raw Blame History