Chimeraforge

로컬 우선(local-first), 모델 비종속적(model-agnostic) LLM 배포 플래너. "어떤 모델, 양자화, GPU, 백엔드를 써야 하며 -- 몇 대나 필요한지, 맞을지, SLO를 충족할지, 비용이 얼마인지"를 셸, Python, 또는 AI 어시스턴트에서 빠르고 정직하며 측정된 답으로 바꿔 줍니다.

uvx chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"

신뢰 원칙

모든 숫자는 measured, estimated, 또는 unknown으로 표시되며, 이 도구는 뒷받침할 수 없는 숫자는 절대 속여 만들지 않습니다. VRAM과 KV-cache는 모델의 실제 아키텍처에서 계산됩니다(정확함). 처리량은 가능하면 측정값 조회를 사용하고, 그 외에는 명시적인 대역폭 로플라인(roofline) 추정치입니다 -- 결코 실제 데이터인 것처럼 제시되지 않습니다. 번들 코퍼스가 다루지 못하는 품질은 지어낸 점수가 아니라 unknown으로 보고합니다. 결과가 0개인 플랜은 막연한 "아무것도 찾지 못함" 대신 모든 후보를 거부한 정확한 게이트를 명명합니다. 텔레메트리 없음, 홈 호출(phone-home) 없음, 에어갭(air-gapped) 환경에서 작동합니다.

모델을 입력하면 -- 크기 클래스, Hugging Face 저장소, Ollama 태그, 또는 미출시 모델용 수동 재정의(manual override) -- (모델 x 양자화 x 백엔드 x GPU 수 x 텐서/파이프라인 병렬화) 공간을 VRAM, 품질, 지연 시간, 비용, 에너지, 그리고 옵트인 안전 게이트에 대해 검색한 다음, SLO를 충족하는 가장 저렴한 구성을 돌려줍니다.

12개 명령, 하나의 도구: plan - suggest - measure - validate - catalog - safety - bench - eval - compare - refit - report - mcp.

경험적 코퍼스는 기술 보고서 TR108-TR137(소비자 GPU에서의 약 204,000개의 실제 측정값)에 근거합니다. 전체 기능 이력은 CHANGELOG에서 확인하세요.

Related MCP server: infra-advisor-mcp

설치

설치 없이 사용해 보기:

uvx chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"
pipx run chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"

실제 설치:

pip install chimeraforge            # planner + model resolution (HF/Ollama) + suggest/measure/safety/bench
pip install chimeraforge[bench]     # + GPU environment metadata for benchmarks (pynvml)
pip install chimeraforge[mcp]       # + MCP server so Claude/GPT/Cursor can call the planner
pip install chimeraforge[eval]      # + quality evaluation (BERTScore, ROUGE-L)
pip install chimeraforge[refit]     # + coefficient refitting (numpy, scipy)
pip install chimeraforge[all]       # everything

Python 3.10+. 핵심 설치에는 플래너와 네트워크 관련 명령이 포함됩니다(httpx는 핵심 의존성). plan / suggest / catalog는 완전히 오프라인으로 실행되며, bench / measure / safety는 실행 중인 백엔드(Ollama, vLLM 또는 TGI)가 필요합니다. Windows / macOS / Linux.

빠른 시작

# Plan a registry size class on your GPU
chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --request-rate 2.0

# Plan ANY model -- a Hugging Face repo or an Ollama tag
chimeraforge plan --model Qwen/Qwen2.5-7B-Instruct --hardware "RTX 4090 24GB"
chimeraforge plan --model ollama:qwen3:14b --ollama-url http://localhost:11434

# Split a model too big for one GPU across several (tensor parallelism)
chimeraforge plan --model meta-llama/Llama-3.3-70B-Instruct --hardware "H100 80GB" --tp 4

# Shrink the KV-cache, print the cost/latency/quality trade-off menu
chimeraforge plan --model-size 8b --hardware "RTX 4080 12GB" --kv-quant q8 --pareto

# Benchmark a live model and plan on the MEASURED numbers
chimeraforge plan --model qwen3:14b --measure

# Discover + rank what fits your GPU and budget
chimeraforge suggest --source ollama --hardware "RTX 4090 24GB" --budget 500

MCP 서버 -- Claude / GPT / Cursor에 동일한 숫자 제공

GPU 크기 산정은 어시스턴트가 정확히 실패하는 지점입니다. 학습 컷오프 시점의 하드웨어 가격과 사양, 그리고 기억에 의존해 수행하는 오류가 쉬운 KV-cache/배칭 산술 때문입니다. chimeraforge mcp는 stdio MCP 서버를 실행하여 어시스턴트가 추측 대신 측정된 데이터를 바탕으로 실제 플래너를 호출하게 합니다.

pip install "chimeraforge[mcp]"

Claude Code:

claude mcp add --transport stdio chimeraforge -- uvx --from "chimeraforge[mcp]" chimeraforge mcp

Claude Desktop / Cursor(MCP 구성 파일에 추가):

{
  "mcpServers": {
    "chimeraforge": {
      "command": "uvx",
      "args": ["--from", "chimeraforge[mcp]", "chimeraforge", "mcp"]
    }
  }
}

--from "chimeraforge[mcp]"는 MCP SDK를 가져오며, uvx는 서버를 자체 포함(self-contained) 환경에서 실행합니다. 클라이언트가 시작하는 환경에 이미 pip install "chimeraforge[mcp]"를 수행했다면, 대신 "command": "chimeraforge", "args": ["mcp"]를 사용할 수 있습니다.

세 가지 도구를 노출합니다: chimeraforge_plan(전체 게이트 검색), chimeraforge_resolve_model(모델 ID를 실제 파라미터/아키텍처에 근거시킴), chimeraforge_list_hardware. 모든 결과는 CLI와 동일한 measured / estimated / unknown 출처(provenance)를 전달하며, 도구 설명은 모델이 자신의 지식보다 이 결과를 우선하도록 안내합니다. chimeraforge_plan은 또한 launch 필드(권장 구성의 서브(serve) 명령)를 반환하므로, 어시스턴트는 플래그를 지어내지 않고도 "그리고 어떻게 실행하나요"에 답할 수 있습니다.

명령어

plan -- 예측 용량 플래너

chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --request-rate 2.0
chimeraforge plan --model Qwen/Qwen2.5-7B-Instruct --hardware "RTX 4090 24GB"   # any HF repo
chimeraforge plan --model ollama:qwen3:14b --ollama-url http://localhost:11434  # any Ollama tag
chimeraforge plan --model meta-llama/Llama-3.3-70B-Instruct --hardware "H100 80GB" --tp 4   # multi-GPU
chimeraforge plan --model-size 3b --kv-quant q4 --pareto                       # smaller KV cache, trade-off menu
chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --launch          # + the serve command to actually run it
chimeraforge plan --model-size 3b --workload agent --safety-target 0.85 --json

• 모든 모델 플래닝: 레지스트리 크기 클래스, HF 저장소(org/name), Ollama 태그, 또는 수동 재정의(--params-b/--n-layers/...).

• (모델 x 양자화 x 백엔드 x N-레플리카 x 배치/GPU)를 5-게이트 파이프라인으로 검색: VRAM -> 품질 -> 안전(옵트인) -> 지연 시간 -> 예산.

• 실제 서빙 물리 현상을 모델링: 연속 배칭(vLLM/TGI), 프리필/디코드 분리(TTFT + TPOT), KV-cache에 묶인 동시성, 그리고 변동성 인지 대기열(--workload).

• GPU 하나에 너무 큰 모델도 맞춤: --tensor-parallel/--tp {N|auto}는 가중치 + KV를 N개 GPU에 샤딩하고(Megatron 스타일, 통신 모델링 포함); --pipeline-parallel/--pp {N|auto}는 대신 레이어를 N개 스테이지로 분할합니다(느린 인터커넥트에서 더 저렴, 파이프라인을 채우려면 배칭 필요). 아직 조합 불가.

• 백엔드가 서빙하는 것만 서빙: GGUF 양자화는 Ollama에서 제공되고, vLLM/TGI는 FP16과 FP8(FP8 텐서 코어가 있는 GPU 전용 -- Ada/Hopper/Blackwell/CDNA3)을 지원합니다. 플래너는 더 이상 vLLM에서 llama.cpp 속도로 가격이 매겨진 GGUF 체크포인트를 제안하지 않습니다.

• KV-cache 양자화(--kv-quant {fp16,q8,q4})는 캐시를 줄이고 최대 동시성을 높입니다 -- 긴 컨텍스트에서 가장 큰 이점.

• 비용 현실성(--duty-cycle, --gpu-price-multiplier): 헤드라인 $/1M-tok은 포화 상태 팜 기준 가격입니다. 프로비저닝된 헤드룸과 모든 유휴 시간에 대해서도 비용을 지불하므로, 2 req/s의 8B에서 유효 수치는 용량 기준 $0.92에 비해 완전 가동 시 $2.71/1M, 30% 가동 시 $9.04/1M입니다. 스팟/예약 가격은 번들된 추측이 아니라 사용자 입력값입니다.

• 자체 호스팅 vs API 손익분기(--compare-api): 워크로드 가격을 호스팅 API와 비교 산정하고 자체 호스팅이 유리해지기 시작하는 월간 볼륨을 보고합니다. 가격은 공급자별 소스 URL이 있는 날짜가 찍힌 스냅샷이며, 90일이 지나면 오래된 것으로 표시됩니다 -- 결코 실시간 견적으로 제시되지 않으며 -- 프론티어 API는 동급으로 속이지 않고 별도의 품질 계층으로 표시됩니다.

• 프리픽스 캐싱(--prefix-cache-hit-rate): 챗봇과 에이전트 트래픽은 긴 시스템 프롬프트를 재사용하므로 프리필의 대부분이 이미 캐시되어 있습니다. 4k 프롬프트와 90% 히트율에서 8B는 TTFT가 166ms에서 17ms로 줄어듭니다. 기본값은 0이며 절대 추론되지 않습니다. 공유 프리픽스가 절약하는 KV도 의도적으로 차감하지 않습니다 -- KV를 과소 산정하면 '맞을 것'이 OOM으로 바뀌기 때문입니다.

• 추론(Reasoning) 모델(--reasoning-tokens N): 숨겨진 생각 토큰은 호출자가 결코 보지 못하지만 GPU에서 디코드되고 KV에 보관됩니다. 보이는 출력만 계산하면 추론 비율만큼 디코드를 과소 계산합니다 -- 자체 점검에서 숨겨진 토큰 1000개가 8B 플랜의 p95를 363ms에서 6128ms로 만들었습니다. 기본값은 0이며 절대 추론되지 않습니다: 이 비율은 가중치가 아니라 워크로드의 속성입니다.

• 어텐션 구조를 고려한 KV: MLA(DeepSeek-V2/V3)는 헤드별 K/V 대신 압축된 잠재 벡터를 캐시합니다 -- GQA로 크기를 산정하면 DeepSeek-V3의 캐시를 57배 과대 평가합니다 -- 그리고 슬라이딩 윈도우 모델은 윈도우를 지나서는 캐시를 늘리지 않습니다. 레이어 패턴이 선언되지 않은 윈도우는 적용되지 않습니다. KV를 과소 산정하면 '맞을 것'이 OOM으로 바뀌기 때문입니다.

• Mixture-of-Experts 인지: VRAM은 전체 파라미터 기준으로 크기를 산정하고(모든 전문가가 상주) 처리량과 TTFT는 활성 파라미터를 사용합니다(토큰은 라우팅된 전문가만 읽습니다). MoE 모델을 밀집 모델로 취급하면 Mixtral-8x7B에서 처리량을 3.6배, DeepSeek-V3에서 약 18배 과소 예측합니다. 활성 수치는 모델의 실제 전문가 구조에서 파생되며 공개된 수치와 일치합니다.

• 에너지(--electricity-rate): 월간 kWh 비용, $/1M-tok (+energy), 와트당 tok/s을 예산 게이트에 포함하지 않고 나란히 보고합니다.

• 실행 명령 내보내기(--launch): 승리 구성에 대해 플랜 자체의 컨텍스트 길이, TP/PP 차수, 배치 크기, KV dtype이 채워진 vllm serve / ollama run / TGI docker run 명령을 생성합니다 -- 수동 계산 시 오류가 발생하기 쉬운 플래그들입니다. 파생할 수 없는 것은 지어내지 않습니다: GGUF 양자화 수준은 지어낸 --quantization 플래그가 아니라 네이티브 동급 체크포인트를 서빙하라는 메모가 됩니다.

• 예측별 출처(measured / estimated / unknown); 맞는 것이 없을 때 바인딩 게이트를 설명합니다.

• 레지스트리 데이터로 검증됨: VRAM R^2=0.968, 처리량 R^2=0.859, 품질 RMSE=0.062, 지연 시간 MAPE=1.05%(분석적 M/D/1보다 20.4x 우수, TR133). ML 없음 -- 경험적 조회 테이블과 제일 원리 기반 보간(레지스트리 외 모델은 로플라인).

suggest -- 모델 검색 및 순위 지정

chimeraforge suggest --source ollama --hardware "RTX 4090 24GB" --budget 500
chimeraforge suggest --source hf --hf-limit 8 --hardware "RTX 4080 12GB"
chimeraforge suggest --source catalog --hardware "RTX 4080 12GB"   # offline, after `catalog --build`

후보를 라이브 Ollama(/api/tags), HF Hub(상위 text-generation), 및/또는 로컬 카탈로그에서 가져옵니다; 각각을 실제 파라미터/아키텍처로 해석하고, 동일한 게이트 검색을 실행한 후 모델별 최상의 구성을 보여줍니다.

measure -- 실시간 벤치마크, 실제 숫자로 플래닝

chimeraforge measure --model qwen3:14b --ollama-url http://localhost:11434
chimeraforge plan --model qwen3:14b --measure   # measure then plan in one step

라이브 모델(실제 N=1 처리량, 서비스 시간, 동시성 확장)을 벤치마킹하고 로컬 코퍼스에 통합합니다. 그러면 plan / suggest는 자동으로 측정된 숫자를 우선합니다(출처가 measured로 바뀝니다).

catalog -- 로컬 모델 카탈로그

chimeraforge catalog --build         # resolve a curated seed (+ --with-ollama) and cache specs
chimeraforge catalog                 # list the cached catalog

해석된 사양을 유지하여 suggest --source catalog가 완전히 오프라인에서 검증된(known-good) 세트의 순위를 매기게 합니다.

safety -- 실시간 거절 선별

chimeraforge safety --model llama3.2-3b --prompts harmful.txt --quant Q4_K_M --safety-target 0.85

plan --safety-target이 번들 TR134/TR142 데이터로 결정하는 반면, safety는 측정합니다: 라이브 모델에 대해 사용자의 프로브 프롬프트를 실행하고, 거절을 분류하며(규칙 기반 -- TR134 정규식 베이스라인), 측정된 거절률을 번들 게이트 데이터와 비교(기대값, 드리프트, RTSI 위험 등급)하여 보고하고, --safety-target 미만이면 코드 1로 종료합니다. 프롬프트는 사용자가 제공합니다(--prompts, 줄당 하나) -- 공격 코퍼스는 패키지에 포함되지 않습니다; HarmBench / AdvBench / 자체 세트를 지정하세요. 실행 중인 Ollama가 필요합니다.

bench -- 실시간 추론 벤치마킹

chimeraforge bench --model llama3.2-3b --runs 5
chimeraforge bench --model llama3.2-3b --all-quants --context 512,1024,2048,4096 --json
chimeraforge bench --model llama3.2-3b --backend vllm --base-url http://localhost:8000

세 가지 워크로드 프로필(단일 / 배치 / 서버-푸아송); 처리량, TTFT, 지연 시간을 p50/p90/p95/p99로 측정; CV 기반 안정성 경고; JSON 출력.

eval -- 품질 평가

chimeraforge eval --task general_knowledge --json
chimeraforge eval --predictions preds.txt --references refs.txt --model llama3.2-3b

메트릭: 정확히 일치(exact match), ROUGE-L(LCS 폴백), BERTScore, 일관성(coherence) -> 종합 점수(0.2*EM + 0.3*ROUGE + 0.3*BERT + 0.2*coherence). 품질 등급은 TR125에서 가져옴; 내장 태스크 3개(general_knowledge, summarization, code). --fp16-baseline을 전달하면 하락 등급을 분류합니다.

compare -- 벤치마크 실행 비교

chimeraforge compare --baseline run1.json --candidate run2.json,run3.json --json

구성을 (model, backend, quant, workload, context_length) 기준으로 매칭합니다; 처리량/TTFT/지속 시간 델타를 계산하고 종합 개선/회귀 요약을 제공합니다.

refit -- 플래너 계수 업데이트

chimeraforge refit --bench-dir ./results/ --output fitted_models.json --validate

베이지안 블렌딩(키별 신뢰도 가중치), 하드웨어 오프셋, 멱법칙(power-law) 재적합, 그리고 쓰기를 게이트하는 10-체크 검증 스위트(--validate).

report -- 리포트 생성

chimeraforge report --results-dir ./results/ --format markdown --output report.md

Markdown(GitHub 호환) 및 자체 포함(self-contained)된 XSS-safe HTML; 구성별 백분위수 테이블과 함께 통계 분석(RMSE, MAE, MAPE, R^2).

mcp -- 플래너를 AI 어시스턴트에 제공

chimeraforge mcp

위에서 설명한 stdio MCP 서버를 실행합니다. pip install "chimeraforge[mcp]"가 필요합니다.

모델링되는 것

하드웨어: 22개 GPU -- 컨슈머 Ada + Blackwell(RTX 30/40/50 시리즈), 데이터센터(A100 40/80GB, H100, H200, B200, L4, T4), AMD MI300X -- 각각 VRAM, 대역폭, FP16 TFLOPS, TDP, 인터커넥트(NVLink/Infinity Fabric/PCIe) 포함.

알려진 한계(솔직하게): 추측 디코딩은 아직 모델링되지 않음. 프리픽스 캐싱은 프리필 절감만 모델링하고 KV 절감은 모델링하지 않음(의도적으로 보수적). 추론 토큰은 모델링되지만 비율은 사용자 입력(--reasoning-tokens)이며 절대 추론하지 않음. MoE의 경우 활성 대비 전체 파라미터는 모델링되지만, 전문가 병렬화와 라우팅 부하 불균형은 모델링되지 않음. vLLM/TGI의 양자화 커버리지는 FP16 + FP8(AWQ/GPTQ는 아직 미지원); FP8 품질은 측정이 아닌 추정치. TP 및 PP 처리량은 통신 모델링 기반 추정치이며 측정치가 아니고, 하나의 플랜에서 결합할 수 없음. 큐잉은 해석적(분산 인지)이며 이산 이벤트 시뮬레이터가 아님. 번들 코퍼스는 주로 한 대의 장비(RTX 4080 12GB)에 맞춰 피팅됨; 다른 GPU는 사용자가 직접 measure할 때까지 대역폭/컴퓨트로부터 스케일링됨. MCP 서버는 stdio 전용(Claude Code/Desktop, 로컬 Cursor) -- 호스팅 원격 전송은 아직 없음.

연구가 결정한 사항

2단계(TR123-TR133, 약 106,000회 측정)는 아티팩트 기반 배포 프레임워크로 정제됨 -- 플래너가 적용하는 것과 동일한 규칙:

핵심 발견(전체 데이터는 TR 문서에 있음): Rust가 Python 단일 에이전트 대비 우세(+15.2% 처리량, -58% TTFT, -67% 메모리 -- TR112); 이중 Ollama가 단일 인스턴스의 82.2% 대비 거의 완벽한 멀티 에이전트 병렬성(~99%) 달성(TR110/TR113/TR114); vLLM의 연속 배칭이 N=8에서 2.25배 이점을 제공하며, 병목은 스택이 아닌 GPU 메모리 대역폭(TR130-TR132).

전체 연구: docs/archive/technical_reports.md에 32개 보고서 전체가 색인되어 있음; 방법론과 원시 데이터 참조가 포함된 전체 아카이브는 outputs/publish_ready/reports/에 있음.

수치가 만들어지는 방식

• 약 204,000회의 1차 측정 -- RTX 4080 Laptop(12GB)에서 32개 기술 보고서(TR108-TR137 + TR142/TR146 안전성 출처)에 걸쳐 수행. 중복 제거: TR137/TR142는 이미 집계된 데이터의 종합.

• 엄격성: 실행별 신선한 프로세스 격리(웜 캐시 편향 없음), 강제 콜드 스타트, 통계적 신뢰도를 위한 구성당 3-5회 실행, 전체 출처가 포함된 구조화된 JSON/CSV 로깅. 모든 주장은 직접 재실행할 수 있는 원시 데이터로 추적 가능.

• 프로그램 맥락: ChimeraForge는 상위 Banterhearts 프로그램(54개 TR에 걸친 약 1,337,000회의 1차 + 심사 측정)의 실행 가능한 CLI 접합부; 안전성 공격 표면과 서빙 스택 연구는 자매 저장소에 있음.

• 549개 자동화 테스트(pytest tests/)가 플래너 모델, 게이트 탐색, 리졸버, 디스커버리, 안전성, 벤치 백엔드, MCP 서버를 커버 -- GPU 분리형으로, 핵심 스위트는 라이브 백엔드가 필요 없음.

어떤 수치든 재현하려면: outputs/publish_ready/reports/ 아래 보고서에서 주장을 찾고, 데이터 폴더로의 참조를 따라가고, CSV/JSON을 검사하고, 제공된 스크립트나 노트북을 재실행하세요. docs/archive/methodology.md 참조.

저장소 구조

문서

• docs/README.md -- 문서 색인 및 내비게이션

• docs/quick_start.md -- 첫 벤치마크 실행(Python + Rust)

• docs/API.md -- 패키지용 Python API 참조

• docs/archive/technical_reports.md -- 32개 기술 보고서 전체 색인

• docs/archive/dual_ollama_setup.md -- 멀티 에이전트 결과 재현에 필요

• docs/archive/methodology.md / docs/archive/rust_vs_python.md -- 방법론 및 전체 언어 비교

기여

기여 환영 -- CONTRIBUTING.md 참조. 좋은 영역: 추가 벤치마크 구성, 새로운 최적화 전략, 더 많은 모델/하드웨어, 문서, 분석 도구.

라이선스

MIT -- LICENSE 참조.

감사의 말

Banterhearts LLM 성능 연구 프로그램의 일환으로 수행됨: 1단계(TR108-TR122)는 측정 방법론과 교차 언어 비교를 확립했고, 2단계(TR123-TR133)는 배포 프레임워크와 용량 플래너를 생산했으며, 3단계(TR134-TR137)는 추론 최적화의 안전성 비용을 측정 -- 현재 플래너의 옵트인 안전성 게이트가 됨.

저장소: https://github.com/Sahil170595/Chimeraforge - PyPI: https://pypi.org/project/chimeraforge/ - 상태: 베타, 활발히 개발 중