Tau本地推理指南：用内置llama.cpp后端在终端免费跑私有Coding Agent

Tau本地推理指南：用内置llama.cpp后端在终端免费跑私有Coding Agent

【免费下载链接】tauA Python port of Pi’s minimalist coding agent.项目地址: https://gitcode.com/gh_mirrors/tau16/tau

Tau 是一个运行在终端里的 Python Coding Agent，它内置了 llama.cpp 本地推理后端。本指南带你用/local命令接入本机模型，在不依赖云端 API 的前提下免费跑一个私有 Coding Agent——读文件、改代码、执行命令全部在本地完成，代码与数据不出机器，既保护隐私又零成本。

为什么要在终端做本地推理

云端大模型方便，却有三个绕不开的痛点：

• 隐私：你的源码会发到第三方服务器。
• 成本：按 token 计费，重度使用账单可观。
• 依赖网络：断网或限流时助手直接"罢工"。

Tau 的内置 llama.cpp 后端 正好解决这三点：模型跑在你自己的显卡/统一内存上，Tau 通过标准 OpenAI 兼容协议与它通信，不联网、不收费、代码不出本机。

💡 一句话理解架构：tau_coding（应用层）→tau_agent（可复用大脑）→tau_ai（模型传输层）。本地推理只是tau_ai的一条"动态 Provider"通道，核心循环完全复用云端模型那套事件流。

准备工作：安装 Tau 与 llama.cpp

第一步：安装 Tau

Tau 以tau-ai包发布，安装后即可得到tau命令（需 Python 3.12+）：

uv tool install tau-ai # 或 pipx install tau-ai tau --version

第二步：准备 llama.cpp 推理服务器

llama-server需要单独安装（属于 llama.cpp 项目，非 Tau 组件）。Tau不会替你安装、启动或停止它，你只需让它保持运行。官方推荐的"路由模式"启动方式——不带模型参数启动，由服务器统一管理模型的下载/加载/卸载：

llama-server \ --models-max 1 \ --parallel 1 \ --flash-attn auto

关键参数速记：

⚠️ 若显存充足、模型支持 65536 token 上下文，可追加--ctx-size 65536 --cache-type-k q8_0 --cache-type-v q8_0使用长上下文档位。q8_0KV 缓存比默认f16更省显存且精度更好；若加载失败，优先调低--ctx-size。

服务器默认监听http://127.0.0.1:8080。

在 Tau 中配置/local连接本地模型

Tau 用统一的 provider 无关入口/local管理本地后端（没有/llama或/llama-cpp别名）。内置 Provider ID 为llama.cpp。

进入 Tau 后执行：

/local

选择被标记为Recommended的llama.cpp后端并确认（即使它当前是唯一选项也要确认，保持入口的通用性）。Tau 会按以下优先级探测有效端点，只探测这一个地址，绝不扫描端口、进程或局域网：

1. 通过Configure提交的 URL
2. 已保存的端点
3. 当前进程的LLAMA_BASE_URL
4. 默认http://127.0.0.1:8080

鉴权（可选）

本地服务器通常无需密钥，三种方式任选：

• 在/local的 secret 字段输入密钥 → 存到~/.tau/credentials.json
• 设置环境变量LLAMA_API_KEY（仅当次会话生效）
• 两者都留空 → 不发送Authorization头

已保存的密钥优先于LLAMA_API_KEY。密钥绝不会写入 llama.cpp 状态文件、会话或诊断日志。

选择并运行你的本地模型

配置完成后用/model打开选择器，会显示服务器真实上报的模型 ID 与显示名（来自/v1/models，无需伪造模型 ID）。

在脚本或新会话中，建议显式指定，最稳：

tau --provider llama.cpp --model <model-id> tau --provider llama.cpp --model <model-id> --print "summarize this project"

规则要点：

• Print 模式（无头）遇到多模型时必须给精确--model，Tau 不会悄悄替你换一个模型。
• 本地推理不是自动全局兜底——你没显式选它时，它不会阻塞常规启动。
• 已有安全快照时，服务器短暂宕机也不影响显式启动。

安全集成快照保存在~/.tau/state/extensions/llama.cpp.json，只含归一化端点、所选模型引用、白名单元数据与时间戳，带版本、加锁、原子替换且权限私有。

进阶：Router 模式下的模型管理与 Hugging Face 下载

当/props识别出兼容的路由器（受测构建区间b9688–b10595）时，/local会解锁完整管理能力；不兼容的构建安全降级为只读的/v1/models发现，推理仍可用。

模型区与操作区分离，方向键在区内移动、Tab直接切区，只有聚焦区高亮：

• 加载/卸载：对unloaded模型标为available to load，按 Enter 审阅加载确认；已有模型在运行时，Tau 会问你保留还是卸载，绝不替你决定。
• 搜索 Hugging Face 模型：输入关键词，打开可方向键导航的仓库/量化列表，展示门控状态与体积，Q4_K_M仅作 UI 推荐。
• 下载精确模型：输入owner/repository[:quantization]，先弹出确认框展示已知体积，再请求服务器端下载。/local显示整行进度条与已传/剩余字节；关闭窗口不会停止 llama.cpp 的下载，重开会自动重新附着进度，并可用Cancel active download…显式取消。

🔑 门控仓库需先在 Hugging Face 上接受条款。Tau 仅读取HF_TOKEN用于搜索，不保存也不转发它；真正下载的是独立运行的 llama.cpp 进程，那个进程需要自己的HF_TOKEN。

Doctor 诊断是显式动作，独立报告：端点可达性 → 模型发现 → 流式 → 工具 schema 接受 → 实际工具调用。模型能流式却不发探针工具时，会给出"兼容性警告"而非"连接失败"，并提示可能是 GGUF 聊天模板不支持工具。

常见问题排查（Troubleshooting）

核心模块路径参考

想读懂这套集成的实现，可按下列路径入手：

• 内置后端注册入口：llama_cpp/init.py
• 服务与端点归一化：llama_cpp/service.py
• 状态与快照持久化：llama_cpp/state.py
• 路由器能力与版本门控：llama_cpp/router.py
• 用户文档（随包内置）：data/docs/local-inference.md
• 站点版指南：guides/local-inference.md
• 设计蓝本（Issue #602 实现计划）：plans/602-built-in-local-inference.md

小结

只需三步，就能在终端免费拥有一个不出门的私有 Coding Agent：

1. uv tool install tau-ai安装 Tau；
2. 独立启动llama-server（路由模式最省心）；
3. 在 Tau 里跑/local→ 选llama.cpp→/model开跑。

隐私、成本、离线三件事，一次性解决。

【免费下载链接】tauA Python port of Pi’s minimalist coding agent.项目地址: https://gitcode.com/gh_mirrors/tau16/tau