Engineering-Konfiguration zur Rettung abstürzender lokaler LLMs in Mac-Docker
TuBrief 편집팀
2026년 8월 14일
0
Computing/Software원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
Wenn man den Quellcode eines Open-Source-AI-Workspaces herunterlädt und in Docker auf dem Mac ausführt, stößt man bereits beim ersten Prompt an eine Wand. Obwohl man zweifellos einen M-Series-Chip verwendet, heulen nur die Lüfter auf und es wird eine erbärmliche Geschwindigkeit von gerade einmal etwas mehr als 10 Token pro Sekunde erreicht. Der Grund dafür ist, dass die Virtualisierungsschicht von Docker Desktop die Apple Silicon GPU (Metal) nicht an den Container durchreichen kann, wodurch das System auf reine CPU-Berechnungen zurückfällt.
Wenn man diesen Flaschenhals nicht behebt und das Ganze mit einem FastAPI-Backend und einer lokalen Vektordatenbank verknüpft, stürzt der Container aufgrund von Speicherlecks und Verbindungserschöpfung ab. Dies sind die vier Einstellungen, die überarbeitet werden müssen, um Code, den man rein nach GitHub-Stars ausgewählt hat, in einer lokalen Umgebung auf Produktionsniveau zu betreiben.
Docker Desktop unter macOS läuft auf einer leichten Linux-VM. Es gibt keine Funktion, um die Metal-GPU-API des Hosts direkt in den Linux-Guest-OS-Container durchzureichen. Ollama oder llama.cpp im Inneren des Container schlagen bei der VRAM-Zuweisung fehl und schalten im Stillen auf CPU-Berechnungen um. Das ist der Grund, warum ein Llama 3 8B Modell, das auf einem M3 Max nativ 40 bis 80 t/s liefert, in dem Moment, in dem es in Docker läuft, auf 21,45 t/s bei der Prompt-Auswertung und 12,17 t/s bei der Token-Generierung einbricht.
`
[Mechanismus des CPU-Fallbacks innerhalb des Virtualisierungscontainers]
+-----------------------------------------------------------------------+
| Docker Container (Linux Guest OS) |
| +---------------------+ |
| | Local LLM Engine | --(VRAM Allocation Req)--> [VirtGPU Missing] |
| +---------------------+ | |
| | v |
| +<--(Fallback to CPU Execution)--- [Silent slog.Debug] |
+-------------|---------------------------------------------------------+
v
[Apple Silicon Host CPU (ARM Neon/DotProd)] -> Geschwindigkeitsabfall
`
Auch die Standardeinstellung für den gemeinsam genutzten Speicher (shm) ist problematisch. Die Standardzuteilung von 64 MB führt bei umfangreichen Tensor-Berechnungen sofort zu einem Bus Error. Öffnen Sie ~/.docker/daemon.json, um den gemeinsamen Speicher zu erweitern und die Ressourcenlimits aufzuheben.
`json
{
"builder": {
"gc": {
"defaultKeepStorage": "20GB",
"enabled": true
}
},
"experimental": false,
"default-shm-size": "8g"
}
`
`yaml
version: '3.8'
services:
llm-inference-engine:
image: ollama/ollama:latest
container_name: local_llm_engine
shm_size: '16gb'
ipc: host
deploy:
resources:
limits:
cpus: '8.0'
memory: 24G
reservations:
cpus: '4.0'
memory: 12G
ports:
- "11434:11434"
volumes:
- ollama_storage:/root/.ollama
volumes:
ollama_storage:
`
Um innerhalb des Containers GPU-Beschleunigung herauszuholen, muss man zu Podman mit dem Virtual Machine Monitor libkrun und dem krunkit-Treiber wechseln. Dabei handelt es sich um eine Methode, bei der Vulkan-Berechnungsanfragen aus dem Inneren des Containers an die Metal-API des macOS-Hosts übergeben werden (Virtio-GPU Venus). Dadurch wird die Verarbeitungsgeschwindigkeit auf bis zu 75 % des nativen Metal-Werts gesteigert.
brew tap slp/krunkit && brew install krunkit podmanexport CONTAINERS_MACHINE_PROVIDER="libkrun" && podman machine init --cpus 8 --memory 32768 && podman machine startpodman machine ssh "ls -la /dev/dri"`dockerfile
FROM fedora:40
RUN dnf -y install dnf-plugins-core &&
dnf -y copr enable slp/mesa-krunkit fedora-40-aarch64 &&
dnf -y install mesa-vulkan-drivers vulkan-loader vulkan-tools &&
dnf -y downgrade mesa-vulkan-drivers.aarch64 --repo copr:copr.fedorainfracloud.org:slp:mesa-krunkit &&
dnf clean all
ENV GGML_VULKAN=1
`
Wenn aus Infrastrukturgründen nur CPU-Berechnungen verwendet werden dürfen, nutzen Sie das Quantisierungsformat Q4_0_4_4, das auf die Vektorbefehle ARMv8.4-A DotProduct und Neon abgestimmt ist. Dadurch wird die Prompt-Auswertungsgeschwindigkeit auf bis zu 50,63 t/s gehalten und die Verarbeitungszeit im Vergleich zur Standard-Docker-CPU-Ausführung um mehr als die Hälfte reduziert.
| Laufzeitkonfiguration | Prompt-Auswertung (t/s) | Token-Generierung (t/s) | Einrichtungsschwierigkeit | Eigenschaften |
|---|---|---|---|---|
| Docker Desktop (Standard-CPU) | ~21,45 | ~12,17 | Gering | CPU-Fallback durch Virtualisierungseinschränkungen |
| Docker Container (ARM Q4_0_4_4) | ~50,63 | ~14,01 | Mittel | Nutzung von ARM-Neon-Vektorbefehlen |
| Podman + libkrun (Vulkan Venus) | ~75% im Vergleich zu Nativ | ~75% im Vergleich zu Nativ | Hoch | Virtio-GPU-Beschleunigung im Container |
| Host Native Metal + Container | Nativ 100% (40-80) | Nativ 100% | Mittel | Struktur zum direkten Aufruf der Host-Engine |
Open-Source-Backends weisen oft ein mangelhaftes Statusmanagement für asynchrone Tasks oder eine unzureichende Garbage-Collector-Verarbeitung von CPython auf. Mit zunehmender Anzahl von Anfragen bläht sich der Speicher auf, bis der Prozess schließlich abstürzt. Mit tracemalloc werden die Stellen ermittelt, die den Speicher auffressen.
`python
import gc
import tracemalloc
tracemalloc.start()
def log_memory_snapshot():
snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')
print("[Memory Debug] Top 5 Allocations:")
for stat in top_stats[:5]:
print(stat)
gc.collect()
`
Der Speicher muss auf Ebene der Prozessverwaltung gewaltsam bereinigt werden. Es wird ein Lebenszyklus eingerichtet, bei dem Gunicorn-Worker nach jeweils 1.000 verarbeiteten Anfragen eigenständig den Speicher freigeben und sich neu starten.
`bash
gunicorn
--workers 4
--worker-class uvicorn.workers.UvicornWorker
--bind 0.0.0.0:8000
--max-requests 1000
--max-requests-jitter 100
--timeout 120
--keep-alive 5
--preload-app
app.main:app
`
Durch das Hinzufügen von --max-requests-jitter 100 wird verhindert, dass alle 4 Worker gleichzeitig abstürzen und neu starten, wodurch das Verschlucken von Anfragen vermieden wird. Nicht antwortende Aufgaben werden nach einem Timeout von 120 Sekunden abgebrochen.
Wenn ein Benutzer den Browser schließt, während eine Antwort generiert wird, und der asynchrone Generator seine Schleife weiter ausführt, werden Rechenressourcen sinnlos verschwendet. Durch die Überprüfung von request.is_disconnected() wird die Schleife bei einer getrennten Verbindung sofort verlassen.
`python
import asyncio
import gc
import logging
from typing import AsyncGenerator
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import StreamingResponse
app = FastAPI(title="Production AI Workspace Backend")
logger = logging.getLogger("stream_logger")
async def robust_llm_token_stream(prompt: str, request: Request) -> AsyncGenerator[str, None]:
try:
for token_idx in range(2000):
if await request.is_disconnected():
logger.warning(f"[Stream Aborted] Client disconnected at step {token_idx}.")
break
await asyncio.sleep(0.01)
yield f"event: message\ndata: {\"id\": {token_idx}, \"text\": \"chunk_{token_idx} \"}\n\n"
except asyncio.CancelledError:
logger.info("[Stream Cancelled] Task cancelled by ASGI server.")
raise
except Exception as err:
logger.error(f"[Stream Error] Error during streaming: {str(err)}")
raise
finally:
logger.info("[Stream Cleanup] Releasing context and triggering GC.")
gc.collect()
@app.post("/api/v1/chat/stream")
async def chat_stream_endpoint(request: Request, body: dict):
prompt = body.get("prompt", "")
if not prompt:
raise HTTPException(status_code=400, detail="Prompt string is missing.")
return StreamingResponse(
robust_llm_token_stream(prompt, request),
media_type="text/event-stream",
headers={
"Cache-Control": "no-cache",
"Connection": "keep-alive",
"X-Accel-Buffering": "no"
}
)
`
Es kommt häufig vor, dass ein einzelnes Upstream-Minor-Update den Build des lokalen Containers beschädigt. Mit einer requirements.txt, die SHA-256-Hashes enthält, werden Paketmanipulationen und Versionskonflikte verhindert.
`plaintext
fastapi==0.110.0 --hash=sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
uvicorn==0.28.0 --hash=sha256:2c6a81387e0037a34ca6a7f8087796030c79eb299f116515822ee483c6604e43
pydantic==2.6.4 --hash=sha256:d82e212f451f2d6c19f5a5e3a89369322e70e1781297587786411516279f64a5
sqlalchemy==2.0.28 --hash=sha256:a611116c2bb45f8f3077e6822ec3a37b384ff6b9a84d4dd88a0e8eb876b5cf12
`
Um zu verhindern, dass Downloads über pip fehlschlagen, wenn Docker in einer Offline-Umgebung wie einem Unternehmenssicherheitsnetzwerk oder im Flugzeug neu gebaut wird, werden Wheel-Binaries im Voraus in einem lokalen Verzeichnis abgelegt.
`bash
pip wheel --wheel-dir=./wheels_repository -r requirements.txt
`
`dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY ./wheels_repository /app/wheels_repository
COPY requirements.txt .
RUN pip install --no-cache-dir --no-index --find-links=/app/wheels_repository -r requirements.txt
COPY . .
CMD ["gunicorn", "-k", "uvicorn.workers.UvicornWorker", "-c", "gunicorn.conf.py", "app.main:app"]
`
Wenn man Änderungen aus dem Upstream-Git-Repository blind per pull übernimmt, gehen die mühsam eingerichteten lokalen Konfigurationen verloren. Stattdessen wird ein Optimierungsbranch erstellt und nur die benötigten Commits werden per Cherry-Pick übernommen.
`bash
git remote add upstream https://github.com/opensource-ai-workspace/workspace.git
git fetch upstream
git checkout -b feature/local-mac-optimization
git cherry-pick
`
Wenn mehrere Agenten gleichzeitig Vektorsuche, Speicherabfragen und Chat-Protokollierung ausführen, läuft der PostgreSQL-Verbindungspool im Handumdrehen leer. Basierend auf einer Einzelplattenumgebung mit Apple Silicon und 8 Kernen wird der Engine-Pool gemäß der Verbindungsformel () auf unter 17 begrenzt.
`python
from sqlalchemy.ext.asyncio import create_async_engine
DATABASE_URL = "postgresql+asyncpg://postgres:password@localhost:6432/ai_workspace"
engine = create_async_engine(
DATABASE_URL,
pool_size=15,
max_overflow=5,
pool_timeout=10,
pool_recycle=300,
pool_pre_ping=True
)
`
Das Problem, dass Agenten während des Wartens auf LLM-Inferenzergebnisse die DB-Sitzungen blockieren, wird durch das Transaktions-Pooling von PgBouncer unterbunden.
`ini
[databases]
ai_workspace = host=postgres_db port=5432 dbname=ai_workspace auth_user=postgres
[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = plain
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
idle_transaction_timeout = 60
max_client_conn = 1000
default_pool_size = 20
min_pool_size = 5
reserve_pool_size = 5
reserve_pool_timeout = 3
`
`
+-------------------------------------------------------------------------------+
| Docker Internal Isolated Network (internal: true) |
| |
| +--------------------+ +--------------------+ +-----------------+ |
| | AI Workspace App | ---> | PgBouncer Proxy | ---> | PostgreSQL DB | |
| | (FastAPI Backend) | | (Port 6432) | | (Port 5432) | |
| +--------------------+ +--------------------+ +-----------------+ |
| | | |
| | [pool_mode = transaction] |
| | [idle_tx_timeout = 60s] |
| v |
| +--------------------+ |
| | Local Vector DB | (Externe Internetkommunikation blockiert) |
| | (Qdrant) | |
| +--------------------+ |
+-------------------------------------------------------------------------------+
`
Um das Risiko von Datenlecks auszuschließen, wird das Container-Netzwerk mit internal: true versehen, um die externe Cloud-Kommunikation zu blockieren. Die Verbindung zur hochrasanten Metal-Ollama-Laufzeitumgebung, die direkt auf dem Host-Computer läuft, erfolgt ausschließlich über das Gateway host.docker.internal.
`yaml
version: '3.8'
services:
backend-app:
build: .
environment:
- DB_HOST=pgbouncer
- DB_PORT=6432
- VECTOR_DB_HOST=vector-db
- OLLAMA_HOST=http://host.docker.internal:11434
networks:
- isolated_local_net
extra_hosts:
- "host.docker.internal:host-gateway"
ports:
- "8000:8000"
pgbouncer:
image: edoburu/pgbouncer:latest
environment:
- DB_HOST=postgres_db
- DB_PORT=5432
- DB_USER=postgres
- DB_PASSWORD=secret
- POOL_MODE=transaction
networks:
- isolated_local_net
depends_on:
- postgres_db
postgres_db:
image: postgres:16-alpine
environment:
- POSTGRES_DB=ai_workspace
- POSTGRES_PASSWORD=secret
volumes:
- pgdata:/var/lib/postgresql/data
networks:
- isolated_local_net
vector-db:
image: qdrant/qdrant:v1.9.0
volumes:
- qdrant_data:/qdrant/storage
networks:
- isolated_local_net
etworks:
isolated_local_net:
driver: bridge
internal: true
volumes:
pgdata:
qdrant_data:
`
Indem man GPU-Virtualisierungsengpässe über Podman oder Host-Bridges umgeht und den Lebenszyklus durch Worker-Wiederverwendung und DB-Proxys steuert, entsteht eine eigenständige Entwicklungsumgebung, die selbst auf Laptops mit M-Series-Chips nicht abstürzt.