llm-localfirst

로컬 우선 LLM 라우팅 — 민감한 데이터와 대량 텍스트 작업은 자체 모델에서 처리하고, 어려운 부분만 클라우드에 호출하세요.

대부분의 LLM 라우터는 비용이나 장애 조치를 위해 어느 클라우드 공급자를 호출할지 최적화합니다. llm-localfirst는 기본값을 뒤집습니다: 자체 로컬 모델을 먼저 실행하고(Ollama / vLLM / LM Studio), 작업이 진정으로 필요할 때만 클라우드에 접근합니다. 주류 라우터가 제공하지 않는 두 가지를 추가합니다:

1. 🔒 실패 시 차단되는 프라이버시 라우팅. sensitive=True로 표시한 호출은 로컬 모델에 고정되며 절대 클라우드로 폴백될 수 없습니다. 로컬 모델이 다운되면 호출은 예외를 발생시킵니다 — 프롬프트를 조용히 제3자 API로 보내지 않습니다.

2. 🤝 매니저-워커 위임. 클라우드 "디렉터" 에이전트에게 토큰이 많이 소모되고 위험이 낮은 텍스트 작업(요약 / 초안 / 번역 / 재구성 / 추출 / 분류)을 빠른 로컬 워커에 오프로드하는 드롭인 도구를 제공합니다 — 클라우드 비용을 줄이고 대량 데이터를 자체 하드웨어에 유지합니다. (프로덕션 Pydantic AI 에이전트에서 추출됨)

여기에 모델 허용 목록 가드(임의의 모델 문자열은 거부됨 — SSRF/비용 폭발 반경 제어), 캐시된 연결 가능성 프로빙, MCP 서버 래퍼, CLI가 포함됩니다.

다섯 줄로 보는 프라이버시 보장

from llm_localfirst import Router, LocalUnavailable

router = Router.from_env()
try:
    out = router.complete("Redact all PII from this record.",
                          source=customer_record, sensitive=True)
except LocalUnavailable:
    # Local model is down. We did NOT send the record to the cloud. You decide.
    ...

sensitive=True는 이 데이터가 박스를 벗어나면 안 된다는 의미입니다. 라우터는 누출보다 실패를 선택합니다. 이러한 비대칭성 — 민감한 호출은 실패 시 차단되고, 일반 대량 호출은 클라우드로 폴백됨 — 이것이 바로 이 제품입니다.

Related MCP server: OpenAI-Compatible MCP Gateway

설치

pip install llm-localfirst              # the routing brain — zero provider SDKs
pip install "llm-localfirst[openai]"    # + talk to local Ollama/vLLM/LM Studio (and cloud OpenAI)
pip install "llm-localfirst[anthropic]" # + Claude (the default cloud fallback / reason model)
pip install "llm-localfirst[all]"       # everything (also: mcp, pydantic-ai)

결정 경로(decide())는 어떤 공급자 SDK도 임포트하지 않으므로, 코어만 설치하고도 라우팅을 검사하고 — 전체 테스트 스위트를 실행할 수 있습니다.

60초 퀵스타트 (Ollama)

ollama pull qwen2.5:7b          # any OpenAI-compatible local server works
pip install "llm-localfirst[openai,anthropic]"
export ANTHROPIC_API_KEY=sk-ant-...   # only needed for the cloud fallback / reason path

from llm_localfirst import Router, Kind

router = Router.from_env()

# 1) Inspect routing WITHOUT spending a token.
print(router.decide(kind=Kind.BULK))     # -> local  (cheap + private)
print(router.decide(kind="reason"))      # -> cloud  (the hard part)
print(router.decide(sensitive=True))     # -> local  (pinned; never cloud)

# 2) Actually run it. Bulk work prefers local, and falls back to cloud only if local is down.
print(router.complete("Summarize this in one sentence.",
                      source=long_text, kind=Kind.BULK).text)

또는 셸에서:

llm-localfirst doctor                      # show config, the allowlist, and local up/down
llm-localfirst route "summarize this" --kind bulk
llm-localfirst route "redact this" --sensitive    # exits non-zero if local is down (fail-closed)

라우팅 결정 방식

decide()는 로컬 모델에 연결할 수 있는지(캐시됨) 프로빙한 후 다음 규칙을 순서대로 적용합니다:

명시적 model은 허용 목록에 있는 이름이어야 합니다. 임의의 문자열(또는 잘못된 URL)은 ModelNotAllowed를 발생시킵니다. 이 허용 목록이 SSRF/비용 가드입니다 — 호출자는 라우터를 새 엔드포인트나 구성되지 않은 비싼 모델로 지정할 수 없습니다.

매니저-워커 위임 (Pydantic AI)

클라우드 디렉터가 계획과 도구 호출을 유지하고, 단순 텍스트 작업을 로컬 워커에 오프로드하세요:

from pydantic_ai import Agent
from llm_localfirst import Router
from llm_localfirst.integrations.pydantic_ai import attach_worker

router = Router.from_env()
director = Agent("anthropic:claude-haiku-4-5", system_prompt="...")

# Adds a `delegate_to_worker(task, source)` tool that routes to your LOCAL model.
# attach_worker REFUSES a non-local worker, so delegated source text can't leak.
attach_worker(director, router, worker_model="local",
              on_delegate=lambda task, result: ...)  # optional observability hook

디렉터는 요약, 초안, 번역, 재구성, 추출에 delegate_to_worker를 호출합니다. 이러한 작업은 클라우드 토큰을 소모하는 대신 GPU에서 실행됩니다. examples/manager_worker.py를 참조하세요.

MCP 네이티브

라우터를 모든 MCP 클라이언트(Claude Desktop, IDE, 에이전트)에 세 가지 도구로 노출합니다 — route(건식 결정), complete, usage(이 세션에서 지출한 금액):

pip install "llm-localfirst[mcp]"
llm-localfirst mcp        # serves over stdio

클라우드 지출 상한

프라이버시 보장은 *이 호출이 머신을 벗어나도 되는가?*라는 질문에 답합니다. 로컬 우선 설정이 답해야 할 또 다른 질문은 *머신을 벗어난 것이 이미 얼마나 비용이 들었는가?*입니다.

모든 완료는 자동으로 기록됩니다 — 구성도, 플래그도 필요 없습니다:

router = Router.from_env()
router.complete("summarise this", source=long_document)

router.ledger.calls("cloud")            # 1
router.ledger.tokens("local")           # Usage(input_tokens=..., output_tokens=...)
router.ledger.snapshot()                # JSON-safe, for logs

상한을 설정하면 초과 지출 대신 중단됩니다 — 프라이버시 고정과 동일한 실패 시 차단 자세를 비용에 적용한 것입니다:

from llm_localfirst import Budget, Router

router = Router(..., budget=Budget(max_cloud_tokens=200_000))
...
llm_localfirst.BudgetExceeded: cloud token budget spent: 203_400/200_000 tokens

로컬 호출은 절대 게이트되지 않습니다. 로컬 호출을 제한하면 로컬 실행의 의미가 사라집니다 — 클라우드 예산이 소진되면 클라우드만 닫히고 대량 작업은 계속 흐릅니다.

또는 비용 기준으로, 가격이 필요합니다:

export LF_PRICES='{"haiku": [0.8, 4.0], "sonnet": [3.0, 15.0], "opus": [15.0, 75.0]}'
export LF_MAX_CLOUD_COST=5.00

의도적으로 하지 않는 두 가지:

• 가격 테이블을 제공하지 않습니다. 가격은 변하고, 하드코딩된 낡은 숫자는 숫자가 없는 것보다 나쁩니다. 사용자가 직접 제공해야 합니다 — 그리고 비용 상한은 허용 목록의 클라우드 모델 중 가격이 없는 모델이 있으면 $0.00으로 조용히 앉아서 절대 발동하지 않는 대신 시작을 거부합니다. max_cloud_tokens와 max_cloud_calls는 정확하며 구성이 전혀 필요 없습니다.

• 단일 호출을 제한하지 않습니다. 토큰 수는 공급자가 응답한 후에만 존재하므로, 상한은 위반 후 다음 클라우드 호출을 차단합니다. 초과분을 한 번의 호출로 제한할 수는 있지만, 한 번의 호출 자체를 제한할 수는 없습니다.

원장은 Router 범위의 메모리에 존재합니다. 프로세스의 가드 레일이지 청구서가 아닙니다 — 프로세스 간 지출을 강제해야 한다면 ledger.snapshot()을 자체 저장소에 유지하세요.

llm-localfirst complete "..." --usage    # tally on stderr, completion on stdout
llm-localfirst doctor                    # shows the budget and which models are priced

비교

llm-localfirst는 아닙니다 — 일반 다중 공급자 게이트웨이가 아니며, 그렇게 되려고 하지 않습니다. 명확하고 공정하게 말하자면: LiteLLM과 Bifrost는 이미 로컬 모델(Ollama, vLLM)로 라우팅할 수 있습니다 — 로컬 기능은 차별점이 아닙니다. 차별점은 실패 시 차단되는 프라이버시 고정, 매니저-워커 위임 도구, 그리고 로컬 우선 기본 자세입니다.

수십 개의 공급자를 지원하는 광범위한 클라우드 게이트웨이가 필요하다면 LiteLLM을 사용하세요. 개인 데이터가 설계상 로컬에 유지되고 대량 작업이 자체 하드웨어에서 실행되길 원한다면, 이 라이브러리가 바로 그것입니다.

이것이 아닌 것

• 다중 클라우드 게이트웨이가 아닙니다. 하나의 로컬 백엔드 + Claude(+ 선택적 OpenAI)를 제공합니다. 허용 목록에 등록하여 추가할 수 있습니다. 수백 개의 공급자 shim을 만들지는 않습니다.

• 콘텐츠 분류기가 아닙니다. 사용자가 호출을 sensitive=True로 태그합니다(또는 kind를 선택). 텍스트가 개인 정보인지 추측하지 않습니다 — 사용자가 선언한 것을 강제합니다.

• 로드 밸런싱이나 의미론적 캐싱이 아닙니다. 그것들은 게이트웨이 기능입니다. 이것은 프라이버시 보장이 있는 라우팅 정책입니다.

• 비용 분석이나 청구가 아닙니다. 지출 상한은 대시보드가 아닌 프로세스 내 가드 레일입니다: 프로세스가 종료되면 카운트가 재설정되고, 공급자가 보고한 것을 보고합니다. 실제 수치가 필요하면 공급자의 인보이스를 읽으세요.

• 프롬프트 방화벽이 아닙니다. 호출이 어디서 실행되는지 제어하지, 내용이 무엇인지는 제어하지 않습니다.

구성

모든 설정은 환경 변수(접두사 LF_) 또는 .env 파일에서 읽습니다. .env.example을 참조하세요. 주요 항목:

개발

uv venv && uv pip install -e '.[dev]'
ruff check . && pytest

라우팅 핵심(정책, 레지스트리, 라우터, 연결 가능성)은 100% 오프라인으로 테스트됩니다 — 네트워크도 공급자 SDK도 필요 없습니다. 기여는 환영합니다. CONTRIBUTING.md를 참조하세요.

라이선스

MIT © Shaxzodbek Qambaraliyev / Blaze. LICENSE를 참조하세요.