常见错误及解决方法

本文整理了运行 vLLM Semantic Router 时常见的系统日志报错、原因分析及配置修复方案。

提示

可先尝试本页末尾的快速诊断命令。

配置加载错误

创建 ExtProc 服务器失败

Log 模式：

Failed to create ExtProc server: <error>

原因及修复：

原因	修复方法
配置路径无效	验证 --config 标志指向存在的 YAML 文件
YAML 语法错误	使用 yq 或在线验证器验证 YAML
缺少必填字段	检查所有必填字段是否存在

# 验证配置路径
./router --config /app/config/config.yaml

---

读取配置文件失败

Log 模式：

failed to read config file: <error>

修复方法：

• 验证文件存在：ls -la config/config.yaml
• 检查权限：chmod 644 config/config.yaml
• 确保路径是绝对路径或正确的相对路径

参见代码：cmd/main.go。

---

Cache 和存储错误

需要 Milvus 配置路径

Log 模式：

milvus config path is required

修复方法： 使用 Milvus 后端时设置 backend_config_path：

semantic_cache:
  enabled: true
  backend_type: "milvus"
  backend_config_path: "config/milvus.yaml" # ← 添加此项

---

索引不存在且禁用了自动创建

Log 模式：

index <name> does not exist and auto-creation is disabled

修复方法： 在 Redis/Milvus 配置中启用自动创建：

# 在 config/redis.yaml 中
index:
  auto_create: true # ← 启用此项

---

Redis 存储尚未实现

日志模式：

redis store not yet implemented

注意： Redis 响应存储尚不可用。请改用 memory 或 milvus：

semantic_cache:
  backend_type: "memory" # 或 "milvus"

参见代码：pkg/cache 和 pkg/responsestore。

---

PII 和安全错误

请求被 PII 过滤器阻断

当请求因包含敏感信息（个人身份信息 PII）而被阻断时，您将看到类似以下的 403 Forbidden 响应：

{
  "object": "error",
  "message": "PII signal fired: rule=<name>, detected_types=[<types>], threshold=<score>",
  "type": "pii_violation",
  "param": null,
  "code": 403
}

原因：路由器的 PII 模型在这个决策阶段检测到敏感信息（邮件、电话或身份证），且当前策略未将其加入白名单。

修复方法：

1. 允许该 PII 类型（如果应该被允许）— 将其添加到信号规则的 pii_types_allowed 中：

signals:
  pii:
    - name: "pii_allow_location"
      threshold: 0.5
      pii_types_allowed:
        - "GPE"          # 在此添加被拒绝的类型
        - "ORGANIZATION"

2. 提高阈值（如果是误报）：

signals:
  pii:
    - name: "pii_deny_all"
      threshold: 0.95   # 从默认的 0.5 提高

---

检测到 Jailbreak 攻击

日志模式：

Jailbreak detected: type=<type>, confidence=<score>

修复方法：

1. 提高分数阈值（降低误报） — 更新信号规则：

signals:
  jailbreak:
    - name: "jailbreak_standard"
      threshold: 0.85   # 从默认的 0.65 提高

2. 为特定决策旁路检查（例如内部工具通道） — 在该决策的条件中不引用验证特征：

decisions:
  # 该决策不引用任何 jailbreak 信号 → 无 jailbreak 检查
  - name: "internal_decision"
    priority: 100
    rules:
      operator: "OR"
      conditions:
        - type: "keyword"
          name: "internal_keywords"
    modelRefs:
      - model: "internal-model"

参见代码：pii/policy.go 和 req_filter_jailbreak.go。

---

MCP 客户端错误

必须指定命令或 URL

日志模式：

either command or URL must be specified

修复方法： 指定传输配置：

# 对于 stdio 传输
mcp_clients:
  my_client:
    transport_type: "stdio"
    command: "/path/to/mcp-server"

# 对于 HTTP 传输
mcp_clients:
  my_client:
    transport_type: "streamable-http"
    url: "http://localhost:8080"

---

stdio 传输需要命令

日志模式：

command is required for stdio transport

修复方法： 为 stdio 传输添加命令：

mcp_clients:
  my_client:
    transport_type: "stdio"
    command: "python"
    args: ["-m", "my_mcp_server"]

参见代码：pkg/mcp/factory.go。

---

Endpoint 错误

地址格式无效

Log 模式：

invalid endpoint address: <address>

修复方法：

错误格式	正确格式
http://10.0.0.1:8000	10.0.0.1（地址）+ 8000（端口）
vllm.example.com	改用 IP 地址
10.0.0.1:8000	分开地址和端口字段

vllm_endpoints:
  - name: "endpoint1"
    address: "10.0.0.1" # 仅 IP，不含协议/端口
    port: 8000 # 端口单独设置

参见：config.yaml#vllm_endpoints 和 pkg/extproc。

---

模型加载错误

找不到模型

日志模式：

failed to load model: <path>

修复方法：

• 验证模型路径存在
• 检查模型是否已下载：ls -la models/
• 确保路径在容器内可访问

bert_model:
  model_id: /app/models/all-MiniLM-L12-v2 # 在容器中使用绝对路径

---

性能问题

Cache 命中率低

症状： Cache hit 极低，请求直接穿透到后端产生高延迟

修复方法： 降低 similarity threshold：

semantic_cache:
  similarity_threshold: 0.75 # 从默认的 0.8 降低

# 或按 decision 设置
plugins:
  - type: "semantic-cache"
    configuration:
      similarity_threshold: 0.70

---

分类置信度过低

症状： 许多查询落入 "other" 类别

修复方法： 降低类别阈值：

classifier:
  category_model:
    threshold: 0.5 # 从默认的 0.6 降低

---

快速诊断命令

# 检查配置语法
yq eval '.' config/config.yaml

# 测试 endpoint 连通性
curl -s http://<address>:<port>/health

# 检查模型文件
ls -la models/

# 查看最近 log
docker logs semantic-router --tail 100

# 检查指标
curl -s http://localhost:9190/metrics | grep semantic_router