ModelLens

ModelLens

查看哪些模型真正可用。

一个 MCP 服务，可将任何兼容 OpenAI 的网关转化为一组可观测、可排名的模型。它会发现服务商公布了哪些模型，并探测哪些模型当前可用——延迟、成功率、取消情况、流式响应、工具调用——保留历史记录，并回答**“我该用哪个模型？”**

零第三方依赖。仅使用 Python 3.9+ 标准库。

---

为什么需要它

如果你使用多个模型服务商，就已经遇到了这个问题：

• 网关说它提供 89 个模型。实际上有多少个能响应？
• 今天哪个模型最快？昨天的答案已经过时了。
• 你的路由器会选择列表中的第一项——而第一项速度很慢。
• 用户投诉之前，故障都无从察觉。

ModelLens 让这一切一目了然。它让你不再盲目信任模型列表，而是实际进行测量。

来自一个在线网关的真实示例（89 个模型，已探测 16 个）：

magpie/kilo/nvidia/nemotron-3.5-super-vl:free     97.6  100.0%    0.0%      628ms   healthy
magpie/auto/beam-free                             96.6  100.0%    0.0%      909ms   healthy
magpie/longcat/LongCat-2.5                        88.4  100.0%    0.0%     3104ms   mixed
magpie/group/daily                                70.0  100.0%    0.0%    77345ms   mixed
magpie/radeon-cloud/DeepSeek-V4.1-Flash           70.0  100.0%    0.0%    87388ms   mixed
magpie/nvidia/deepseek-ai/deepseek-v4.1-flash     0.0    0.0%  100.0%         -    unreliable
magpie/modelscope/Qwen/Qwen3.8-27B                 0.0    0.0%    0.0%         -    quota_blocked

默认路由组把一个耗时 87 秒的模型排在第一位，却把一个耗时 0.9 秒的模型排在第三位。ModelLens 一次探测就发现了这个问题。

---

安装

# from PyPI
pip install modellens-mcp
modellens --config config.json --data history.json --once ranking

也可以直接从源码运行——无依赖，无需安装：

curl -fsSL https://raw.githubusercontent.com/Greatbeing/modellens/main/modellens.py -o modellens.py
python3 modellens.py --config config.json --data history.json --once ranking

配置

{
  "endpoints": [
    {"name": "magpie",  "base_url": "http://127.0.0.1:3425/v1", "api_key": ""},
    {"name": "openai",  "base_url": "https://api.openai.com/v1", "api_key": "sk-..."},
    {"name": "ollama",  "base_url": "http://127.0.0.1:11434/v1"}
  ]
}

对于 localhost 网关，api_key 可以留空。models 可用于筛选公布的模型列表；enabled: false 可禁用某个端点，而无需将其删除。

作为 MCP 服务运行

让任意 MCP 客户端连接它：

{
  "mcpServers": {
    "modellens": {
      "command": "python3",
      "args": ["/path/to/modellens.py",
               "--config", "/path/to/config.json",
               "--data",   "/path/to/history.json"]
    }
  }
}

支持 Claude Desktop、Cursor、Windsurf、VS Code 和任何其他 MCP 客户端。

DeepSeek Harness

在配置文件的 cordis.patch.yml 中注册它（注意：新增条目需要使用 - insert:，而不能直接使用 - id:——后者表示“修改现有条目”）：

- insert:
    - id: modellens
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: "modellens"
        transport: "stdio"
        command: "python3"
        args:
          - "/data/workspace/modellens/modellens.py"
          - "--config"
          - "/data/workspace/modellens/config.json"
          - "--data"
          - "/data/workspace/modellens/history.json"

然后重启 dsh web。已验证：该服务作为 dsh-web 的子进程运行（pgrep -P $(systemctl --user show dsh-web -p MainPID)）。

工具

工具	功能
list_models	查看各端点公布的模型（可选子字符串筛选）
probe	发送真实请求：延迟、成功率、流式响应、工具调用
ranking	根据记录的历史数据进行质量排名
recommend	为指定配置推荐最佳模型：fast | cheap | capable
report	以 Markdown 呈现完整情况

示例

probe(limit=20, check_tools=true)
ranking(limit=10)
recommend(profile="fast")

---

评分方式

每次探测都会发送真实请求，因此这些数字是实际数据，而非估算值。

指标	权重	说明
成功率	50%	成功率为 0% ⇒ 无论其他指标如何，得分均为 0
中位延迟	30%	线性递减，8 s 时降至 0
取消率	20%	超时和客户端取消

判定结果：healthy（成功率 ≥95%，中位延迟 <3 s）· mixed · unreliable（取消率 ≥30%）· quota_blocked（全部为 429）· dead（全部为 404）· untested。

每个模型的历史记录保存在 history.json 中（保留最新的 200 次探测），因此排名会随着使用而不断完善。

---

命令行工具

该服务也可用作命令行工具：

python3 modellens.py --config config.json --data history.json --once probe --limit 20
python3 modellens.py --config config.json --data history.json --once ranking

---

使用场景

• 挑选模型之前——recommend(profile="fast")
• 服务商停止响应时——ranking 会在用户察觉之前显示其排名下滑
• 路由器出现异常时——比较各组成员，找出速度较慢的模型
• 控制成本——找出从未被选用的高价模型
• 接入新的服务商——探测一次，了解哪些模型真正可用

---

状态与路线图

目前已实现：发现、探测、流式响应／工具调用检查、评分、排名、推荐、Markdown 报告、MCP stdio 传输、CLI。

路线图：目前仅支持兼容 OpenAI 的 /v1/models；计划支持 Anthropic 和 Gemini 传输、按端点核算成本、告警 Webhook，以及面向多团队的托管版本。

---

许可证

MIT。随意使用、发布，也可以为你自己的托管版本收费。

---

诚实说明

• 探测会消耗令牌。 每次探测都会实际调用一次补全。请合理设置 limit，不要每分钟探测上百个模型。
• 单次探测的证据很弱。 多次探测后，评分才有意义；报告会显示 n=1，以便你了解样本量。
• 延迟取决于你。 测量结果不仅受提供商影响，还受你的网络影响。请在 Agent 运行的环境中运行。