# Generate 请求（完全兼容 Ollama 客户端）
curl http://omlx-server:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "Why is the sky blue?",
  "stream": false,
  "options": {
    "temperature": 0.7,
    "num_predict": 256
  }
}'

# Chat 请求
curl http://omlx-server:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": true
}'

# Embedding 请求
curl http://omlx-server:11434/api/embeddings -d '{
  "model": "nomic-embed-text",
  "prompt": "Hello world"
}'

{registry}/{namespace}/{model}:{tag}
├── library/qwen2.5:7b          → 默认 7B-Q4_K_M 量化
├── library/qwen2.5:7b-q8_0     → Q8_0 量化版本
├── library/qwen2.5:7b-fp16     → FP16 全精度
└── library/qwen2.5:7b-instruct → 指令微调版本

# Pull 指定量化版本
curl http://omlx:11434/api/pull -d '{"model": "qwen2.5:7b-q4_k_m"}'

# 或在 Modelfile 中指定
FROM qwen2.5:7b-q8_0

# OMLX 扩展：列出模型的可用量化版本
curl http://omlx:11434/api/show -d '{"model": "qwen2.5:7b", "verbose": true}'

# 列出模型占用空间
ollama list --omlx-stats
# 输出示例：
# qwen2.5:7b-q4_k_m    4.5 GB  (磁盘)  +  5.8 GB  (显存)  Worker: node-gpu-01

# 清理未使用模型（仅删除磁盘缓存，不影响显存中的活跃模型）
curl -X DELETE http://omlx:11434/api/delete -d '{"model": "unused-model"}'

# OMLX 扩展：批量清理过期缓存
curl -X POST http://omlx:11434/api/omlx/cache/prune -d '{"older_than": "7d"}'

Worker-A 首次加载 qwen2.5:7b
  → 检查本地缓存：未命中
  → 检查共享缓存（MinIO）：命中
  → 从共享缓存读取 GGUF 文件
  → 加载到显存
  → 注册到 Controller

Worker-B 请求相同模型
  → 检查本地缓存：未命中
  → 检查共享缓存（MinIO）：命中
  → 无需重复 Pull，直接加载
  → 加载到显存

# Worker 配置
gpu:
  devices: [0, 1, 2, 3]         # 使用的 GPU 设备列表
  tensor_parallel_size: 2        # 张量并行度（每 2 张 GPU 一组）
  pipeline_parallel_size: 1      # 流水线并行度
  data_parallel_size: 2          # 数据并行副本数（2 组张量并行组）
  # 以上配置对 4 张 GPU：TP=2 × DP=2 → 可同时处理 2 个独立请求

Worker（4 × GPU）
├── GPU 0：qwen2.5:7b 完整副本 → 处理 Req-1, Req-4
├── GPU 1：qwen2.5:7b 完整副本 → 处理 Req-2, Req-5
├── GPU 2：qwen2.5:7b 完整副本 → 处理 Req-3, Req-6
└── GPU 3：qwen2.5:7b 完整副本 → 处理 Req-7

Worker（2 × GPU，TP=2）
├── GPU 0：qwen2.5:72b Layer 0-39（前半）
└── GPU 1：qwen2.5:72b Layer 40-79（后半）
        
单请求 → 同时使用 GPU 0 + GPU 1
GPU 0 计算前半层输出 → NVLink/PCIe → GPU 1 继续计算

worker:
  gpu_selector:
    strategy: "topology"         # 就近 NUMA 节点匹配
    prefer_nvlink: true          # 优先选择 NVLink 互联的 GPU 对
    max_gpu_per_model: 4         # 单模型最大使用 GPU 数量

# 请求中指定 Keep-Alive
curl http://omlx:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "Hello",
  "keep_alive": "30m"           # 请求完成后保留 30 分钟
}'

# OMLX 扩展：手动卸载模型
curl -X POST http://omlx:11434/api/omlx/unload -d '{"model": "qwen2.5:7b"}'

# OMLX 扩展：查询显存使用状态
curl http://omlx:11434/api/omlx/vram/status
# 响应：
# {
#   "worker": "node-gpu-01",
#   "total_vram_gb": 80,
#   "used_vram_gb": 54.2,
#   "loaded_models": [
#     {"name": "qwen2.5:72b", "vram_gb": 45.5, "state": "active"},
#     {"name": "qwen2.5:7b", "vram_gb": 5.8, "state": "keep-alive", "ttl": "3m"},
#     {"name": "nomic-embed", "vram_gb": 1.5, "state": "idle"}
#   ]
# }

后端选择决策树：

模型是否为 GGUF 格式？
├── 是 → llama.cpp（天然兼容）
└── 否（HuggingFace safetensors）
      ├── 追求最高吞吐？ → vLLM
      ├── 需要结构化生成（JSON / Regex）？ → SGLang
      ├── 追求最低延迟？ → TensorRT-LLM
      ├── 长上下文多轮对话？ → SGLang（RadixAttention 优势）
      └── 通用在线推理？ → vLLM（生态最成熟）

# Modelfile 中指定后端
FROM qwen2.5:7b
BACKEND vllm                  # 指定推理后端
PARAMETER tensor_parallel_size 2

# API 请求中覆盖后端
curl http://omlx:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role": "user", "content": "Hello"}],
  "options": {"omlx_backend": "sglang"}
}'

# Worker 配置中声明支持的后端
worker:
  backends:
    - name: vllm
      enabled: true
      models_path: /models/huggingface/
    - name: llama.cpp
      enabled: true
      models_path: /models/gguf/
    - name: sglang
      enabled: false

# GPU Worker Pod 配置示例
apiVersion: v1
kind: Pod
spec:
  nodeSelector:
    node.kubernetes.io/instance-type: gpu-worker
  tolerations:
    - key: "nvidia.com/gpu"
      operator: "Exists"
      effect: "NoSchedule"
  containers:
    - name: worker
      resources:
        limits:
          nvidia.com/gpu: 1

# 添加 OMLX Helm 仓库
helm repo add omlx https://charts.omlx.dev/stable
helm repo update

# 查看可用版本
helm search repo omlx

# 安装 OMLX Stack
helm install omlx omlx/omlx-stack \
  --namespace omlx-system \
  --create-namespace \
  --values custom-values.yaml

# 升级
helm upgrade omlx omlx/omlx-stack \
  --namespace omlx-system \
  --values custom-values.yaml

# 全局配置
global:
  imageRegistry: "docker.io/omlx"
  imageTag: "v0.4.0"
  storageClass: "gp3"
  modelRegistry: "harbor.example.com/models"

# Server 组件
server:
  replicas: 3
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"
  hpa:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - omlx.example.com
    tls:
      - secretName: omlx-tls
        hosts:
          - omlx.example.com

# Gateway 组件
gateway:
  replicas: 3
  resources:
    requests:
      cpu: "1"
      memory: "2Gi"
  config:
    routeStrategy: "least-loaded"      # round-robin / least-loaded / random
    rateLimit:
      enabled: true
      requestsPerSecond: 100
    queueMaxSize: 1000

# Controller 组件
controller:
  replicas: 1
  config:
    leaderElection: true
    healthCheckInterval: 10s
    modelLoadTimeout: 300s

# Worker 组件
worker:
  replicas: 4
  resources:
    limits:
      nvidia.com/gpu: 1
    requests:
      cpu: "8"
      memory: "32Gi"
  config:
    keepAlive: "15m"
    maxLoadedModels: 4
    vramLimit: "38Gi"                # 单 Worker 显存上限
    backends:
      - name: "llama.cpp"
        enabled: true
      - name: "vllm"
        enabled: true
  nodeSelector:
    node.kubernetes.io/instance-type: "gpu-worker"
  persistence:
    enabled: true
    size: "200Gi"
    storageClass: "gp3"

# 模型预加载
models:
  preload:
    - "qwen2.5:7b-q4_k_m"
    - "nomic-embed-text"
    - "llama3.1:8b-q4_k_m"

# 监控集成
monitoring:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: "30s"
  grafanaDashboard:
    enabled: true
    labels:
      grafana_dashboard: "1"

# 认证配置
auth:
  enabled: true
  apiKeys:
    - name: "admin-key"
      key: "omlx-admin-xxxxx"
      role: "admin"
  oidc:
    enabled: false

# 目录结构
omlx-deploy/
├── base-values.yaml          # 公共基础配置
├── dev-values.yaml           # 开发环境覆盖
├── staging-values.yaml       # 预发环境覆盖
└── prod-values.yaml          # 生产环境覆盖

# 部署命令（Helm 合并多 values 文件）
helm install omlx omlx/omlx-stack \
  -f base-values.yaml \
  -f prod-values.yaml \
  --namespace omlx-system

# OMLX Modelfile - Qwen2.5 代码助手
FROM qwen2.5:7b-instruct-q8_0

# 推理参数
PARAMETER temperature 0.3
PARAMETER top_p 0.9
PARAMETER num_predict 2048
PARAMETER repeat_penalty 1.1
PARAMETER stop "</s>"
PARAMETER stop "User:"
PARAMETER stop "Assistant:"

# OMLX 扩展：指定推理后端
BACKEND vllm
PARAMETER tensor_parallel_size 1

# OMLX 扩展：显存管理
PARAMETER omlx_keep_alive "30m"

# 系统提示词
SYSTEM """You are an expert software engineer assistant specializing in Go and Python.
Follow these rules:
1. Write clean, idiomatic code
2. Include error handling
3. Add brief comments for complex logic
4. Prefer standard library over third-party packages"""

# 对话模板
TEMPLATE """{{ if .System }}<|system|>
{{ .System }}<|end|>
{{ end }}{{ if .Prompt }}<|user|>
{{ .Prompt }}<|end|>
{{ end }}<|assistant|>
{{ .Response }}<|end|>"""

# 对话示例
MESSAGE user "Write a Go function to read a YAML config file"
MESSAGE assistant "```go\npackage config\n\nimport (\n    \"os\"\n    \"gopkg.in/yaml.v3\"\n)\n\ntype Config struct {\n    Server   ServerConfig   `yaml:\"server\"`\n    Database DatabaseConfig `yaml:\"database\"`\n}\n\nfunc Load(path string) (*Config, error) {\n    data, err := os.ReadFile(path)\n    if err != nil {\n        return nil, fmt.Errorf(\"read config: %w\", err)\n    }\n    var cfg Config\n    if err := yaml.Unmarshal(data, &cfg); err != nil {\n        return nil, fmt.Errorf(\"parse config: %w\", err)\n    }\n    return &cfg, nil\n}\n```"

# 1. 创建 Modelfile
cat > Modelfile.qwen-code << 'EOF'
FROM qwen2.5:7b-instruct-q8_0
SYSTEM "You are a code assistant."
PARAMETER temperature 0.3
EOF

# 2. 构建模型
curl http://omlx:11434/api/create -d '{
  "name": "qwen-code-assistant",
  "modelfile": "FROM qwen2.5:7b-instruct-q8_0\nSYSTEM \"You are a code assistant.\"\nPARAMETER temperature 0.3"
}'

# 或者用 ollama CLI
ollama create qwen-code-assistant -f Modelfile.qwen-code

# 3. 本地测试
ollama run qwen-code-assistant "Write a hello world in Rust"

# 4. 推送到 Registry
ollama push qwen-code-assistant

# 5. 在其他节点拉取
ollama pull qwen-code-assistant

Step 1: Worker-A (Node-1) 计算 Layers 0-26
  → 输出激活值 → RDMA 传输 → Worker-B (Node-2)
Step 2: Worker-B (Node-2) 计算 Layers 27-53
  → 输出激活值 → RDMA 传输 → Worker-C (Node-3)
Step 3: Worker-C (Node-3) 计算 Layers 54-79
  → 输出 Logits → 采样 → Token → 返回 Gateway

**OMLX 分布式推理配置**

**关键网络要求**

| 网络类型 | 带宽 | 延迟 | 适用节点数 |
|---------|------|------|-----------|
| InfiniBand HDR | 200 Gbps | < 2µs | 4+ |
| InfiniBand EDR | 100 Gbps | < 3µs | 2-4 |
| RoCE v2 | 100 Gbps | < 5µs | 2-4 |
| TCP/IP | 25-100 Gbps | > 20µs | 不推荐 |

OMLX 建议仅在超大模型（100B+ 参数）或多节点总算力受限时使用跨节点分布式推理。同等算力下应优先通过垂直扩展（增加单节点 GPU 数量）满足需求，避免跨节点通信开销。

flowchart TB
    G["Gateway 收到请求"]
    G --> S1["1. 解析 model 名称<br/>→ 查 Model-Worker 映射表<br/>（从 Controller 同步）"]
    S1 --> S2["2. 过滤候选 Worker 列表"]
    S2 --> S2A["模型已加载到显存 → 优先级最高"]
    S2 --> S2B["模型已在本地缓存<br/>（未加载到显存）→ 优先级中"]
    S2 --> S2C["模型未缓存（需 Pull）→ 优先级低"]
    S2 --> S3["3. 应用会话亲和性<br/>同一 Session ID 路由至同一 Worker"]
    S3 --> S4["4. 应用标签过滤<br/>Label Selector"]
    S4 --> S5["5. 负载均衡算法选择目标 Worker"]
    S5 --> S6["6. 检查目标 Worker 并发上限"]
    S6 -->|未达上限| Forward["转发请求"]
    S6 -->|已达上限| Fallback["排队或回退至次优 Worker"]
    Forward --> S7["7. 转发请求 → 等待 Worker 响应"]
    Fallback --> S7
```text

**负载均衡算法**

| 算法 | 配置值 | 原理 | 适用场景 |
|------|--------|------|---------|
| 最少加载 | `least-loaded` | 选择当前活跃请求数最少的 Worker | 通用场景，默认策略 |
| 轮询 | `round-robin` | 依次轮询所有候选 Worker | Worker 算力均等 |
| 加权轮询 | `weighted-round-robin` | 按 Worker 权重比例分发 | Worker 算力不均衡 |
| 最少延迟 | `least-latency` | 选择历史平均延迟最低的 Worker | 延迟敏感场景 |
| 随机 | `random` | 随机选择 | 简单测试 |

**会话亲和性配置**

**请求队列与过载保护**

**路由表的动态更新**

# 单文本向量化
curl http://omlx:11434/api/embeddings -d '{
  "model": "nomic-embed-text",
  "prompt": "The sky is blue because of Rayleigh scattering."
}'

# 响应
{
  "embedding": [0.0123, -0.0456, 0.0789, ...],  // 768/1024/4096 维向量
  "model": "nomic-embed-text"
}

# 批量向量化（OMLX 扩展）
curl http://omlx:11434/api/omlx/embeddings/batch -d '{
  "model": "nomic-embed-text",
  "input": [
    "What is Kubernetes?",
    "How to deploy a Pod?",
    "Explain container orchestration."
  ]
}'
```text

**常用 Embedding 模型**

| 模型 | 向量维度 | 最大 Token | 适用场景 |
|------|---------|-----------|---------|
| nomic-embed-text | 768 | 8192 | 通用英文/多语言文本向量化 |
| mxbai-embed-large | 1024 | 512 | 高精度语义检索 |
| bge-m3 | 1024 | 8192 | 多语言检索、稠密+稀疏混合 |
| all-minilm | 384 | 512 | 轻量级快速检索 |
| snowflake-arctic-embed | 1024 | 8192 | 长文档向量化 |

**OMLX Embedding 部署架构**

**Embedding 模型独立部署**

Embedding 模型与生成模型在 OMLX 中可部署在不同的 Worker 节点上，避免竞争生成模型的 GPU 资源：

**RAG Pipeline 示例**

# 单张图片推理
curl http://omlx:11434/api/chat -d '{
  "model": "llava:13b",
  "messages": [
    {
      "role": "user",
      "content": "Describe this image in detail.",
      "images": ["'$(base64 -i image.jpg)'"]
    }
  ],
  "stream": false
}'

# 多张图片推理
curl http://omlx:11434/api/generate -d '{
  "model": "minicpm-v:8b",
  "prompt": "Compare these two charts. Which one shows better performance?",
  "images": ["'$(base64 -i chart1.png)'", "'$(base64 -i chart2.png)'"]
}'

# OMLX 扩展：图片 URL 直接传入
curl http://omlx:11434/api/omlx/chat -d '{
  "model": "qwen2-vl:7b",
  "messages": [
    {
      "role": "user",
      "content": "What is in this image?",
      "image_urls": ["https://example.com/image.jpg"]
    }
  ]
}'
```text

**Vision 模型显存需求**

| 模型 | 语言部分显存（Q4_K_M） | 视觉编码器显存 | 总分 | 推荐 GPU |
|------|---------------------|-------------|------|---------|
| LLaVA 7B | ~4.5 GB | ~1.5 GB | ~6 GB | A10 / 3080 |
| LLaVA 13B | ~8 GB | ~1.5 GB | ~9.5 GB | A100-40G |
| Qwen2-VL 7B | ~4.5 GB | ~2 GB | ~6.5 GB | A10 / 3090 |
| InternVL2 8B | ~5 GB | ~3 GB | ~8 GB | A100-40G |
| MiniCPM-V 8B | ~5 GB | ~1.5 GB | ~6.5 GB | A10 / 3090 |

**多模态推理流水线**

graph TD
    Input["用户输入 + Tools 定义"]
    Analysis["OMLX → 模型分析 → 输出 Tool Call（JSON）"]
    Execute["调用方解析 Tool Call → 执行函数 → 获取结果"]
    Result["Tool Result 回传 OMLX"]
    Final["模型根据结果继续生成最终回复"]

    Input --> Analysis
    Analysis --> Execute
    Execute --> Result
    Result --> Final
```text

**API 调用示例**

**Tool Calling 最佳模型**

| 模型 | Tool Calling 质量 | 备注 |
|------|------------------|------|
| qwen2.5:14b-instruct | 优秀 | 原生训练支持 Tool Use |
| qwen2.5:32b-instruct | 优秀 | 多函数选择准确率高 |
| llama3.1:8b | 良好 | 需明确 System Prompt |
| mistral-nemo:12b | 良好 | 函数调用格式稳定 |
| command-r:35b | 优秀 | Cohere 原生的多步 Tool Use |

**OMLX 并行 Tool Call**

支持一次返回多个 Tool Call，并行执行：

**Tool Call 超时与容错**

# 请求（stream: true）
curl http://omlx:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "Explain quantum computing in simple terms.",
  "stream": true
}'

# SSE 响应流
data: {"model":"qwen2.5:7b","created_at":"2025-01-01T00:00:00Z","response":"Quantum","done":false}
data: {"model":"qwen2.5:7b","created_at":"2025-01-01T00:00:00Z","response":" computing","done":false}
data: {"model":"qwen2.5:7b","created_at":"2025-01-01T00:00:00Z","response":" uses","done":false}
# ... 持续流式返回 ...
data: {"model":"qwen2.5:7b","created_at":"2025-01-01T00:00:00Z","response":"","done":true,"total_duration":3250000000,"load_duration":1200000000,"prompt_eval_count":12,"prompt_eval_duration":150000000,"eval_count":156,"eval_duration":2930000000}
```text

**Chat 流式响应**

**流式输出架构**

**OMLX 的流式增强**

| 增强特性 | 说明 |
|---------|------|
| 断流重连 | Worker 故障时自动切换到备用 Worker，从中断前的 Token 位置继续（需 KV Cache 转移） |
| 背压控制 | Gateway 检测 Client 消费速率低于生成速率时，暂缓 Worker 的 Token 生成 |
| 多路复用 | 同一 HTTP/2 连接承载多个 SSE 流，减少连接数 |
| 流式指标 | 每个 SSE 流的 TTFT / TPOT / Total Duration 记录在 Prometheus 指标中 |
| 流式超时 | `stream_timeout` 配置项控制单个 SSE 连接的最大持续时间，默认 600s |

**非流式 vs 流式对比**

| 维度 | 非流式（stream: false） | 流式（stream: true） |
|------|----------------------|-------------------|
| 首字节时间（TTFB） | 等待全部 Token 生成完成 | 首个 Token 即可返回 |
| 客户端感知延迟 | 高（需等待全部生成） | 低（逐 Token 展示） |
| 网络传输 | 单次 JSON 响应 | 持续 SSE 事件流 |
| 连接占用 | 短连接 | 长连接（需配置超时） |
| 适用场景 | 批处理 / API 调用 / 非交互 | 对话 UI / 实时交互 |

graph TD
    L1["层级 1：Gateway 速率限制（Rate Limiting）<br/>全局 QPS 限制 + 单模型 QPS 限制<br/>超过限制 → HTTP 429 Too Many Requests"]
    L2["层级 2：Gateway 请求队列（Request Queuing）<br/>Worker 并发满时排队等待<br/>超过队列长度 / 超时 → HTTP 503 Service Unavailable"]
    L3["层级 3：Worker 并发上限（Concurrency Limit）<br/>单 Worker 最大并发请求数<br/>到达上限 → 回退至队列或拒绝"]
    L4["层级 4：推理后端批处理（Dynamic Batching）<br/>vLLM / SGLang 将并发请求合并为 Batch<br/>提升 GPU 利用率和吞吐量"]
    GPU["GPU 执行推理"]

    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> GPU
```text

**关键配置参数**

**Dynamic Batching 机制**

**吞吐量估算公式**

**过载保护**

| 保护机制 | 触发条件 | 行为 |
|---------|---------|------|
| Gateway Rate Limit | QPS 超过限制 | HTTP 429 |
| Queue Overflow | 队列长度超过 maxQueueSize | HTTP 503 |
| Worker OOM Guard | 显存使用 > 95% | 拒绝新请求 + 触发模型卸载 |
| Worker Timeout | 单请求执行 > maxTimeout | 终止推理 + HTTP 504 |
| Shedding | Gateway CPU > 90% | 随机舍弃低优先级请求 |

monitoring:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: "30s"
    labels:
      release: "prometheus"
  grafanaDashboard:
    enabled: true
    labels:
      grafana_dashboard: "1"

  # Alert Rules
  alerting:
    enabled: true
    rules:
      - alert: OMLXHighErrorRate
        expr: |
          sum(rate(omlx_server_requests_total{status=~"5.."}[5m]))
          / sum(rate(omlx_server_requests_total[5m])) > 0.05
        for: 5m
        severity: critical
        annotations:
          summary: "OMLX error rate exceeds 5%"

      - alert: OMLXWorkerDown
        expr: omlx_controller_workers_healthy < omlx_controller_workers_total
        for: 2m
        severity: critical
        annotations:
          summary: "OMLX Worker node is down"

      - alert: OMLXVRAMHigh
        expr: omlx_worker_vram_used_bytes / omlx_worker_vram_total_bytes > 0.95
        for: 5m
        severity: warning
        annotations:
          summary: "OMLX VRAM usage exceeds 95%"

      - alert: OMLXQueueHigh
        expr: omlx_gateway_queue_length > 100
        for: 5m
        severity: warning
        annotations:
          summary: "OMLX request queue depth exceeds 100"

graph TD
    Client["Client Request<br/>携带认证凭证<br/>Header: Authorization: Bearer omlx-xxx<br/>Header: Authorization: Bearer jwt_token<br/>Header: X-OMLX-API-Key: omlx-xxx"]
    Server["OMLX Server（认证中间件）<br/>验证 API Key → 查询本地 Key Store<br/>验证 JWT Token → 调用 OIDC Provider（Keycloak / Auth0）"]
    RBAC["RBAC 鉴权<br/>提取用户角色（admin / developer / viewer）<br/>检查角色是否有权限执行当前操作"]
    Gateway["转发至 Gateway"]

    Client --> Server
    Server --> RBAC
    RBAC --> Gateway
```text

**API Key 管理**

**RBAC 角色权限矩阵**

| 操作 | admin | developer | viewer |
|------|-------|-----------|--------|
| Generate / Chat（推理） | 允许 | 允许 | 允许 |
| Embeddings（向量化） | 允许 | 允许 | 允许 |
| Pull Model（拉取模型） | 允许 | 允许 | 禁止 |
| Push Model（推送模型） | 允许 | 允许 | 禁止 |
| Create Model（创建模型） | 允许 | 允许 | 禁止 |
| Delete Model（删除模型） | 允许 | 允许 | 禁止 |
| List Models（列出模型） | 允许 | 允许 | 允许 |
| Show Model（查看详情） | 允许 | 允许 | 允许 |
| Get Metrics（查看指标） | 允许 | 允许 | 允许 |
| Worker Management（Worker 管理） | 允许 | 禁止 | 禁止 |
| API Key Management（密钥管理） | 允许 | 禁止 | 禁止 |
| Config Management（配置管理） | 允许 | 禁止 | 禁止 |

**模型级别的访问控制（OMLX 扩展）**

**JWT Token 验证流程**

**安全配置建议**

| 配置项 | 建议值 | 说明 |
|-------|--------|------|
| TLS | 强制启用 | 生产环境必须加密传输，API Key 不通过明文 HTTP 发送 |
| API Key 轮换 | 90 天 | 定期轮换 API Key，通过 Helm Values 更新 |
| Rate Limit（未认证） | 禁用 | 禁止未认证请求 |
| API Key 最小化 | 按团队/服务分配独立 Key | 便于审计和吊销 |
| OIDC Token 有效期 | < 24h | 短有效期 Token + Refresh Token |

{
  "timestamp": "2025-06-15T10:30:00.123Z",
  "level": "INFO",
  "component": "worker",
  "worker_id": "worker-2",
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "sess-xyz",
  "message": "Inference completed",
  "fields": {
    "model": "qwen2.5:7b",
    "prompt_tokens": 128,
    "completion_tokens": 256,
    "duration_ms": 1250,
    "ttft_ms": 180,
    "tpot_ms": 45,
    "backend": "vllm",
    "gpu_id": 0
  }
}
```text

**审计事件类型**

| 事件 | 触发条件 | 审计字段 |
|------|---------|---------|
| `model.pull` | 拉取模型 | model, registry, size_bytes, duration_ms, user |
| `model.push` | 推送模型 | model, registry, size_bytes, user |
| `model.delete` | 删除模型 | model, user |
| `model.create` | 创建模型 | model, from_model, user |
| `model.load` | Worker 加载模型到显存 | worker, model, vram_used_mb, duration_ms |
| `model.unload` | Worker 卸载模型 | worker, model, reason |
| `api_key.create` | 创建 API Key | key_name, role, creator |
| `api_key.delete` | 删除 API Key | key_name, creator |
| `config.change` | 修改配置 | changed_keys, user |
| `worker.join` | Worker 注册到集群 | worker_id, gpu_model, vram_total, backends |
| `worker.leave` | Worker 离开集群 | worker_id, reason |

**日志集成配置**

**Loki 日志查询示例**

**日志保留策略**

| 日志类型 | 保留时长 | 存储位置 |
|---------|---------|---------|
| 应用日志（DEBUG/INFO） | 7 天 | Loki / Elasticsearch（热存储） |
| 应用日志（WARN/ERROR） | 30 天 | Loki / Elasticsearch |
| 审计日志 | 365 天 | S3 / MinIO 归档 |
| 请求日志 | 30 天 | Loki |

# Modelfile 中设置
FROM qwen2.5:7b
PARAMETER num_ctx 8192           # 上下文窗口 Token 数

# API 请求中动态设置（不得超过模型原生上限）
curl http://omlx:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "...",
  "options": {
    "num_ctx": 4096              # 此请求使用 4096 Token 上下文
  }
}'
```text

**常用模型默认 / 最大上下文长度**

| 模型 | 默认 num_ctx | 最大 num_ctx | 备注 |
|------|-------------|-------------|------|
| qwen2.5:7b | 2048 | 131072 | 支持长上下文 |
| qwen2.5:72b | 2048 | 131072 | 支持长上下文 |
| llama3.1:8b | 2048 | 131072 | 支持长上下文 |
| llama3.1:70b | 2048 | 131072 | 支持长上下文 |
| mistral:7b | 2048 | 32768 | — |
| deepseek-r1:7b | 2048 | 131072 | — |

**上下文超出时的处理策略**

**OMLX Truncation 配置**

**KV Cache 显存占用估算**

**KV Cache 显存预算规划**

| 模型 | 权重显存（Q4_K_M） | KV Cache 显存（8K ctx） | KV Cache 显存（32K ctx） | 总显存（8K ctx） |
|------|-------------------|----------------------|------------------------|----------------|
| qwen2.5:7b | ~4.5 GB | ~0.8 GB | ~3.2 GB | ~5.3 GB |
| qwen2.5:14b | ~8.5 GB | ~1.3 GB | ~5.2 GB | ~9.8 GB |
| qwen2.5:72b | ~45 GB | ~2.5 GB | ~10.0 GB | ~47.5 GB |
| llama3.1:8b | ~5 GB | ~1.0 GB | ~4.0 GB | ~6.0 GB |
| llama3.1:70b | ~40 GB | ~2.5 GB | ~10.0 GB | ~42.5 GB |

OMLX 平台层
├── OMLX Server（Ollama API 兼容）
├── OMLX Gateway（路由 / 负载均衡）
├── OMLX Controller（调度 / 编排）
└── OMLX Worker（推理执行层）
      ├── vLLM Backend         ← 可将 vLLM 作为推理引擎
      ├── llama.cpp Backend
      ├── SGLang Backend
      └── TensorRT-LLM Backend

单独使用 vLLM：
  vLLM OpenAI Server → 需要额外搭建网关、负载均衡、认证、监控

使用 OMLX + vLLM：
  OMLX 管理运维层 + vLLM 提供推理能力 = 完整平台体验

graph TD
    subgraph GS["GPUStack"]
        GSS["Server<br/>(OpenAI API)"]
        GSW["Worker<br/>(llama.cpp)"]
        GSS --> GSW
    end

    subgraph OMLX["OMLX"]
        OMLXS["Server<br/>(Ollama API)"]
        OMLXG["Gateway<br/>路由 / 负载均衡"]
        OMLXC["Controller<br/>调度 / 编排"]
        OMLXW["Worker<br/>(多后端)"]
        OMLXS --> OMLXG --> OMLXC --> OMLXW
    end

层级                    优化手段                    关键参数
────────────────────────────────────────────────────────────
推理引擎层    PagedAttention / KV Cache 管理     max_num_batched_tokens
              Prefix Caching / Chunked Prefill   enable_prefix_caching
              Continuous Batching                max_num_seqs
                                                 
调度层        路由亲和性 / 会话保持               session_affinity_ttl
              请求优先级队列                      omlx_priority
              模型预加载                           precache_models
                                                 
资源管理层    显存池化 / 多 Worker 调度             vram_limit
              GPU 拓扑感知                          gpu_selector.topology
              动态 Batch Size                      max_batch_size
```text

**KV Cache 优化**

**Prefix Caching 工作原理**

请求 A：System Prompt(200 tokens) + User Q1(50 tokens) + Assistant A1(100 tokens)
请求 B：System Prompt(200 tokens) + User Q2(50 tokens) + Assistant A2(100 tokens)
请求 C：System Prompt(200 tokens) + User Q3(50 tokens)

节省 Prefill 时间：

- 无 Prefix Cache：每个请求需计算 200 + 50 = 250 tokens Prefill
- 有 Prefix Cache：每个请求仅计算 50 tokens Prefill
- Prefill 时间节省 ≈ 80%

**Batch Size 调优**

| 参数 | 含义 | qwen2.5:7b 建议 | qwen2.5:72b 建议 | 调优原则 |
|------|------|----------------|-----------------|---------|
| `max_num_seqs` | 最大并发序列数 | 128 | 64 | 设为 GPU 显存可支持的并发数的 0.8 倍 |
| `max_num_batched_tokens` | 单次迭代最大批处理 Token 数 | 8192 | 16384 | 与模型 max_position_embeddings 对齐 |
| `max_model_len` | 单个请求最大 Token 长度 | 8192 | 32768 | 低于此值的请求才接受 |
| `gpu_memory_utilization` | GPU 显存利用率上限 | 0.90 | 0.85 | 72B 模型留更多余量给权重负载 |

**批处理策略**

**性能优化清单**

| 优化项 | 预期收益 | 实施难度 | 适用场景 |
|-------|---------|---------|---------|
| 启用 Prefix Caching | Prefill 延迟降低 50-80% | 低（配置开关） | 多轮对话 / 相同 System Prompt |
| 调整 GPU Memory Utilization | 吞吐提升 10-20% | 低 | 显存未充分利用 |
| 启用 Chunked Prefill | TTFT 降低 30-50% | 低（配置开关） | 长输入场景 |
| 选择 vLLM / SGLang 后端 | 批量吞吐提升 30-60% | 中（模型格式转换） | 高并发在线推理 |
| 数据并行多 Worker | 吞吐线性扩展 | 低（增加 Worker 副本） | 读多写少 |
| 共享存储模型缓存 | 模型拉取延迟降低 80% | 中（搭建 MinIO/CephFS） | 多 Worker 频繁加载模型 |
| RDMA 网络 | 跨节点推理延迟降低 50% | 高（硬件 + 网络配置） | 跨节点分布式推理 |

2. 检查 Worker 日志中的最后输出

   ```bash
   kubectl logs worker-2 -n omlx-system --tail=100
   # 关注：CUDA OOM / GPU Driver Error / Network Timeout
```text

3. 检查 GPU 驱动状态

   ```bash
   kubectl exec worker-2 -n omlx-system -- nvidia-smi
   # 关注：GPU 是否可见、驱动版本是否匹配

5. 检查 Worker 注册状态

   ```bash
   curl http://omlx-controller:11436/api/workers
   # 查看 Worker 心跳时间是否过期

2. 检查 Worker 本地是否有模型文件

   ```bash
   kubectl exec worker-0 -n omlx-system -- ls -lh /var/lib/omlx/models/

4. 检查显存是否足够加载模型

   ```bash
   curl http://omlx:11434/api/omlx/vram/status

2. 检查 Worker 并发请求数

   ```bash
   # Prometheus 指标
   omlx_worker_requests_in_flight{worker="worker-0"}

4. 检查 GPU 利用率

   ```bash
   kubectl exec worker-0 -n omlx-system -- nvidia-smi dmon -s pucv -c 10

2. 检查是否有多余模型占用显存

   ```bash
   # 列出已加载模型及其显存占用
   curl http://omlx:11434/api/omlx/models/loaded

**解决方案**：

- 手动卸载闲置模型：`POST /api/omlx/unload`
- 降低 `num_ctx` 减少 KV Cache 预留
- 降低 `gpu_memory_utilization` 至 0.85
- 将部分模型迁移到其他 Worker

**故障 5：Gateway 路由异常**

**现象**：请求被路由到错误的 Worker，或请求返回 `no available worker`。

**排查步骤**：

1. 检查 Model → Worker 映射表

   ```bash
   curl http://omlx-controller:11436/api/routes

3. 检查 Worker 标签是否匹配

   ```bash
   # 请求中指定了 omlx_worker_label，但无 Worker 持有该标签
   kubectl get pods -n omlx-system -l omrx-label=gpu-a100

# 1. 日常巡检
curl http://omlx:11434/api/omlx/health       # 整体健康状态
curl http://omlx:11434/api/omlx/workers      # Worker 列表
curl http://omlx:11434/api/omlx/vram/status  # 显存分布

# 2. 模型上线
ollama pull qwen2.5:14b                       # 拉取新模型
ollama run qwen2.5:14b --test                 # 功能验证
# 更新 Helm values 添加模型到 preload 列表
helm upgrade omlx omlx/omlx-stack -f values.yaml

# 3. Worker 扩容
helm upgrade omlx omlx/omlx-stack \
  --set worker.replicas=6
# 或使用 kubectl scale（依赖 StatefulSet）
kubectl scale statefulset omlx-worker --replicas=6 -n omlx-system

# 4. 模型下线
curl -X DELETE http://omlx:11434/api/delete \
  -d '{"model": "deprecated-model"}'
# 从 preload 列表中移除
helm upgrade ...

# 5. 灰度发布（Canary）
# 部署新版 Worker StatefulSet（新版本标签）
# Gateway 按标签逐步将流量切至新版 Worker
# 验证无异常后全量切换

# Server - 建议 Request = Limit 避免被驱逐
server:
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "2"
      memory: "4Gi"

# Worker - GPU 任务不要设置 CPU limit（避免 throttling）
worker:
  resources:
    requests:
      cpu: "8"
      memory: "32Gi"
    limits:
      nvidia.com/gpu: 1     # 仅限制 GPU，不设 CPU limit
      memory: "32Gi"        # 内存设置 limit 防止 OOM 波及节点

# Gateway - 适度超卖
gateway:
  resources:
    requests:
      cpu: "1"
      memory: "2Gi"
    limits:
      cpu: "4"
      memory: "4Gi"