常见错误与解决方法
本指南为运行 vLLM 语义路由时可能遇到的常见日志消息和错误提供了快速参考。每个章节都将错误模式映射到其根本原因和配置修复方法。
提示
使用页面末尾的 快速诊断命令 来快速定位问题。
配置加载错误
无法创建 ExtProc 服务器
日志模式
Failed to create ExtProc server: <error>
原因与解决方法
| 原因 | 解决方法 |
|---|---|
| 配置路径无效 | 确认 --config 标志指向现有的 YAML 文件 |
| YAML 语法错误 | 使用 yq 或在线校验工具验证 YAML 格式 |
| 缺少必填字段 | 检查所有必填字段是否已填写 |
# Verify config path
./router --config /app/config/config.yaml
读取配置文件失败
日志模式
failed to read config file: <error>
修复方法
- 验证文件是否存在：
ls -la config/config.yaml - 检查权限：
chmod 644 config/config.yaml - 确保路径是绝对路径或正确的相对路径
查看代码：cmd/main.go。
缓存与存储错误
需要 Milvus 配置路径
日志模式
milvus config path is required
修复： 使用 Milvus 后端时请设置 backend_config_path
semantic_cache:
enabled: true
backend_type: "milvus"
backend_config_path: "config/milvus.yaml" # ← Add this
索引不存在且禁用了自动创建
日志模式
index <name> does not exist and auto-creation is disabled
修复： 在 Redis/Milvus 配置中开启自动创建 (auto-creation)
# In config/redis.yaml
index:
auto_create: true # ← Enable this
Redis 存储尚未实现
日志模式
redis store not yet implemented
注意： Redis 响应存储 (response store) 暂不可用。请改用 memory 或 milvus
semantic_cache:
backend_type: "memory" # or "milvus"
查看代码：pkg/cache 和 pkg/responsestore。
PII 与安全错误
违反 PII 策略
日志模式
PII policy violation for decision <name>: denied PII types [<types>]
修复方法
- 如果该 PII 类型应当被允许，则放行该类型
plugins:
- type: "pii"
configuration:
pii_types_allowed:
- "LOCATION" # Add denied type here
- 如果出现误报，请调高阈值
classifier:
pii_model:
threshold: 0.95 # Increase from default 0.9
检测到越狱攻击 (Jailbreak)
日志模式
Jailbreak detected: type=<type>, confidence=<score>
修复方法
- 调高阈值以减少误报
prompt_guard:
threshold: 0.8 # Increase from default 0.7
- 针对特定决策禁用:
decisions:
- name: "internal_decision"
jailbreak_enabled: false
查看代码：pii/policy.go 和 req_filter_jailbreak.go。
MCP 客户端错误
必须指定命令 (Command) 或 URL
日志模式
either command or URL must be specified
修复： 指定传输配置
# For stdio transport
mcp_clients:
my_client:
transport_type: "stdio"
command: "/path/to/mcp-server"
# For HTTP transport
mcp_clients:
my_client:
transport_type: "streamable-http"
url: "https://: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) 错误
地址格式无效
日志模式
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 only, no protocol/port
port: 8000 # Port separate
模型加载错误
未找到模型
日志模式
failed to load model: <path>
修复方法
- 验证模型路径是否存在
- 检查模型是否已下载：
ls -la models/ - 确保容器内部可以访问该路径
bert_model:
model_id: /app/models/all-MiniLM-L12-v2 # Use absolute path in container
性能问题
缓存命中率低
现象： 缓存极少返回命中，后端延迟高
修复： 调低相似度阈值 (similarity threshold)
semantic_cache:
similarity_threshold: 0.75 # Lower from default 0.8
# Or per-decision
plugins:
- type: "semantic-cache"
configuration:
similarity_threshold: 0.70
分类置信度过低
现象： 许多查询被归类为“其他 (other)”类别
修复： 调低类别阈值 (category threshold)
classifier:
category_model:
threshold: 0.5 # Lower from default 0.6
快速诊断命令
# Check config syntax
yq eval '.' config/config.yaml
# Test endpoint connectivity
curl -s http://<address>:<port>/health
# Check model files
ls -la models/
# View recent logs
docker logs semantic-router --tail 100
# Check metrics
curl -s https://:9190/metrics | grep semantic_router