LLMxRay
看清你的本地 AI 到底在做什么。
把 VS Code Copilot、Open WebUI、Continue、n8n 或你自己的智能体指向 LLMxRay 而不是 Ollama，就能看到每一轮：
哪些已在缓存中、哪些被重新读取、守护进程悄悄截掉了什么、哪个工具挤掉了哪个模型。无云端。无 API 密钥。零成本。
🌐 English •
Français •
中文 •
العربية •
Srpski
快速开始 •
你的工具在发什么 •
保留与转发 •
面向智能体 •
同样包含 •
适用人群 •
安装 •
Ollama 兼容性 •
更新日志
---
## 快速开始
你需要运行 [Ollama](https://ollama.com/download)，并至少拉取一个模型（`ollama pull llama3.2`）。然后：
```bash
npx llmxray
```
或者使用 Docker：
```bash
docker run -p 5174:5174 -p 11435:11435 djovaneli/llmxray
```
现在把你的工具指向 **http://localhost:11435**，而不是 Ollama 的 11434：VS Code Copilot、Open WebUI、Continue、n8n、你自己的脚本。它的行为与 Ollama 完全一致，并转发一切。打开 **http://localhost:5174**，进入 **Live**，看着它们的每一轮到达。
只是想试试某个模型？打开对话页面，选择一个模型，发送一条消息。
---
## 你的工具真正在发什么
你的编辑器、你的智能体和你的脚本都在和同一个 Ollama 对话。这些页面展示每个工具发送了什么、守护进程如何处理，以及这让其他工具付出了什么代价。
### Live：你的其他工具在发什么
LLMxRay 会打开第二个端口 **11435**，它的行为与 Ollama 完全一致，并把一切转发过去。把 VS Code Copilot、Open WebUI、Continue、n8n 或你自己的脚本指向 `http://localhost:11435`，它们发送的每一轮都会出现在这里：客户端、模型、提示大小、来自缓存的比例、预填充与生成速度、工具调用。
```
VS Code Copilot ─┐
Open WebUI ──────┤ ┌─ Live 页面：每一轮、
Continue / n8n ──┼─► http://localhost:11435 ─► Ollama ┤ 缓存命中、预填充速度、
你的脚本 ────────┘ (LLMxRay) └─ 缓存在哪里断裂
```
选中一轮，就能看到提示由什么组成，以及它与上一轮在哪个确切位置开始不再匹配，那就是缓存断裂的地方。发现以平实的句子呈现，每一条都链接到证明它的那一轮：某个客户端每轮都重读整条提示，某个模型部分跑在 CPU 上，工具模式占了每条提示的 40%。只保留计数和时间，在本机保留 30 天，重启后从中断处继续。提示文本是可选项，写入本地文件。除非你把轮次转发到自己的追踪查看器，否则一切不离开你的机器。
默认情况下，两个端口只响应本机，因为 Live 日志保存着你的工具发送的内容。用 `npx llmxray --host 0.0.0.0` 启动，即可让局域网中的其他机器访问，用于第二块屏幕上的 Live 页面或共享的 GPU 机器。
### 提示透视：按比例画出提示本身
你的工具发送的每一轮，都画成一根条。颜色表示提示的每个部分是什么：系统提示、工具模式、之前的轮次、新消息。亮度表示它经历了什么：暗的部分已在模型内存中，不花任何代价；亮的部分必须重新读取；带条纹的部分被守护进程截掉，从未被看到。把一段对话的各轮叠起来，你能看到缓存逐渐增长，看到系统提示里的一个时间戳清空缓存的那一轮，也能看到对话超出上下文、Ollama 悄悄丢掉最早的消息却照样回答的那一轮。如果系统提示本身就太长，被丢掉的是它的开头。点击某个部分，请求会在文本中的对应位置打开。
### 运行：一个工具的工作，从头到尾
一个工具对模型的调用按时间排开，呈瀑布图。每次调用按 Ollama 报告的内容分段：等待、加载模型、读取提示、写出回答。两次调用之间是工具自身的时间，以模型请求的工具命名。每一步从工具开始新对话的地方开始，因此每一步都丢弃缓存的智能体一眼可见，运行开始时模型不在内存中也一样。点击任意一行，可以看到该次调用发送和返回的内容，包括模型的思考和带参数的工具调用，或者某个工具被问了什么、返回了什么。每一行都有自己的链接。在 Live 页面打开*保留提示词文本*即可看到文本；时间数据无需任何设置。
### 共享机器：Ollama 为什么现在很慢，是哪个工具造成的
每个工具一行，按它让其他工具付出的代价（秒）排序：那个发送 `keep_alive: 0`、每次运行后都卸载模型的工具；那个为 4K 的提示请求 128K 上下文、把守护进程降到一次只处理一个请求的工具；那个在它们后面等了 22 秒的工具。每一项都附上要修改的设置。没有造成任何代价的工具也会列出，让你看到好的样子。
### GPU 地图：显存里有什么，还能放下什么
一根与显卡等宽的条：每个已加载的模型是一块，分为权重和上下文额外占用的部分，然后是空闲空间。下面列出每个已拉取的模型，给出三种结论之一：现在就能放下、需要先卸载已加载的模型才能放下、比显卡还大。
### 工具调用：这个模型能驱动智能体吗？
十三种智能体整天都在发送的请求形态，按守护进程返回的结果打分：正确的工具、正确的参数、正确的调用次数、不需要时不调用。每一格都是一句话：“缺少 path 参数”“把调用写进了回答文本”“不需要工具时调用了 search_web”。点击即可看到模型返回的内容。
### 缓存实验室
本地模型只有在提示从第一个 token 起就完全匹配时才会复用提示缓存。顶部的一个时间戳就会让其后的一切作废。缓存实验室找出在轮次间变化的值，指出复用在哪里断掉，然后在你自己的守护进程上**实测**把它们移到末尾能省下多少。
在一条真实的 324 token 提示上实测：时间戳在前时复用 4 个 token、预填充 64.6 ms；时间戳在后时复用 290 个、预填充 18.6 ms。**快 3.5 倍，一字不改。**
### 协议观察台
同一个提示并行通过 Ollama 的三种服务协议：原生 `/api/chat`、OpenAI 兼容 `/v1/chat/completions`、Anthropic 兼容 `/v1/messages`。并排流式输出、按协议统计指标，以及一个封装 diff，展示各协议如何表达结束原因、token 计数和错误。
---
## 保留下来，并继续转发
每一轮的记录（token、缓存、时间、客户端、模型，从不包含文本）在你的机器上保留 30 天，重启后从中断处继续。Live、运行、提示透视和 MCP 工具都会照常继续。
如果你的团队已经在看追踪，就把这些轮次发过去：每次模型调用成为一个带有查看器已能识别的 GenAI 属性的 OpenTelemetry span，每次运行成为一条 trace，两次调用之间的工具时间是单独的 span，与运行页面相同的瀑布图。在 Live 页面填写地址，或设置 `OTEL_EXPORTER_OTLP_ENDPOINT`。
| 查看器 | 地址 |
|---|---|
| Jaeger（`docker run -p 16686:16686 -p 4318:4318 jaegertracing/jaeger`） | `http://localhost:4318` |
| Arize Phoenix（`docker run -p 6006:6006 arizephoenix/phoenix`） | `http://localhost:6006` |
| Langfuse | `https://cloud.langfuse.com/api/public/otel`，加上由你的密钥组成的 Basic 请求头 |
| Grafana Tempo、OpenTelemetry Collector | 它的 OTLP HTTP 地址，通常是 4318 端口 |
只有同时打开*保留提示词文本*和*在每个 span 中包含提示词文本*时，提示词文本才会发送。
---
## 面向智能体
如果你是运行在本地模型上的智能体，LLMxRay 可以告诉你自己的调用出了什么问题。两步。
1. 把你的 Ollama 调用发到端口 **11435**，而不是 11434。它的行为与 Ollama 完全一致，并转发一切；LLMxRay 只记录经过的内容。
2. 把 LLMxRay MCP 服务器加入你的工具：
```json
{ "mcpServers": { "llmxray": { "command": "npx", "args": ["-y", "-p", "llmxray", "llmxray-mcp"] } } }
```
七个工具，全部只读，没有任何内容离开本机：
| 工具 | 回答 |
|---|---|
| `diagnose_my_turns` | 你最近的轮次中有什么突出的问题，以句子给出并附上修复方法：提示超出已加载的上下文而被拒绝、每一轮或某一轮丢失了提示缓存、模型部分运行在 CPU 上、工具模式挤占了提示。 |
| `read_my_last_turn` | 你上一轮的数字：提示 token 及缓存占比、预填充时间与速度、生成的 token 与速度、生成为何停止、提示由什么组成、模型是否放得进显存。 |
| `list_local_models` | 拉取了哪些模型、它们的大小和量化方式、哪些现在已加载以及上下文多大、每个是否放得进显存。 |
| `list_my_turns` | 历史记录：每轮一行，包括 token、缓存占比、预填充、生成速度、停止原因和标记。 |
| `compare_my_turns` | 某个改动是否有帮助：某个时间点前后缓存占比、预填充、速度和提示大小的中位数，并给出结论。 |
| `estimate_my_prompt` | 发送之前：N 个 token 的提示能否放进已加载的上下文、还剩多少余量、模型是否在显存中、缓存能复用多少。 |
| `read_llmxray_status` | LLMxRay 运行在哪里、观察端口、它转发到的 Ollama、它保留了多少轮。 |
LLMxRay 本身必须在运行（`npx llmxray`）。MCP 服务器通过 localhost 读取它。
同样的流程，也有一个你的智能体可以加载的 [Agent Skill](https://agentskills.io)：`npx skills add LogneBudo/llmxray`（skills.sh）或 `clawhub install llmxray-diagnose-ollama-calls`（ClawHub）。源文件：[skills/diagnose-ollama-calls/SKILL.md](skills/diagnose-ollama-calls/SKILL.md)。
给自己起个名字，让你的轮次归你所有：发送请求头 `X-LLMxRay-Client: my-agent`，或把 `http://localhost:11435/?client=my-agent` 用作基础地址，并把 `my-agent` 作为 `client` 传给这些工具。
---
## 同样包含
你在运行一个本地模型。你和它对话。LLMxRay 回答接下来的问题：每个 token 有多快，提示花了多少，缓存有没有起作用，哪个设置其实更好，以及你的*其他*工具在向同一个模型发送什么。
下面的每一页都是其中一个答案。
### 对话，逐 token 呈现
每个 token 在到达时即被绘制，并按模型自己给它的概率（来自 Ollama 的 logprobs）着色。你能看到模型在哪里犹豫、在哪里笃定。支持 Markdown、多轮对话、文件与图片附件、斜杠命令，以及推理模型的思考预算（关闭、由模型决定，或 low / medium / high / max）。
每条回复落地时也会被检查。只有出问题时才会出现标记：重复、拒答、乱码、空回复，或在 token 上限处被截断。
截图
截图
截图
截图
截图
截图
|
|
|
截图
截图
截图
|
|
|
截图
|
|
|
如果 LLMxRay 帮你更好地理解了你的 AI，请考虑给它一颗星。
这能帮助更多人发现这个项目。
