pi-mono 自定义模型实战：一份 models.json 接上你的本地模型

pi-mono 自定义模型实战：一份 models.json 接上你的本地模型

【免费下载链接】piAI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI项目地址: https://gitcode.com/GitHub_Trending/pi/pi

本地 Ollama 模型已经跑起来了，怎么把它接进 pi-mono？答案就一个文件：~/.pi/agent/models.json。它就像 pi-mono 的"模型通讯录"——每个提供商的地址、敲门方式（API 类型）、暗号（apiKey）都记在这里。改完文件重新打开/model就会重新加载，不用重启。

最小配置跑通本地模型

把下面这段存到~/.pi/agent/models.json，Ollama 里的模型立刻就能被 pi 找到。

{ "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "models": [ { "id": "llama3.1:8b" }, { "id": "qwen2.5-coder:7b" } ] } } }

字段说明：

• baseUrl：接口地址。告诉 pi 去哪敲门，本地服务就是本地端口。
• api：敲门方式，决定请求的报文格式。四种可选值见下表。
• apiKey：暗号。Ollama 不校验它，但 pi 要求这个字段存在，随便填个占位值即可。
• models：要暴露的模型列表。每个模型最简只要一个id，也就是发给服务端的模型标识。

api写在 provider 层对全部模型生效，写在 model 层可以单独覆盖。

一行 baseUrl 覆盖内置提供商

想把内置提供商整体走自己的代理，只写一行就够了。

{ "providers": { "anthropic": { "baseUrl": "https://my-proxy.example.com/v1" } } }

baseUrl的作用是把该提供商的所有请求改走你给的地址；内置模型列表和原有鉴权方式继续生效，不用重新定义任何模型。

如果还想往这个提供商里塞几个自定义模型，加一个models数组即可。pi 会按id合并：新 id 是追加，撞了内置 id 就替换。

用 compat 适配半兼容 OpenAI 的服务

接口号称 OpenAI 兼容、请求却被拒时，问题通常出在个别字段的差异上，用compat关掉即可。

{ "providers": { "vllm": { "baseUrl": "http://localhost:8000/v1", "api": "openai-completions", "apiKey": "vllm", "compat": { "supportsUsageInStreaming": false, "maxTokensField": "max_tokens" }, "models": [ { "id": "qwen2.5-coder" } ] } } }

compat的作用是把 pi 的请求改写成你的服务端能接受的格式；provider 层的设置对全部模型生效，model 层可再单独覆盖。

两个常用开关：supportsUsageInStreaming告诉 pi 服务端不支持stream_options，流式里就不再请求用量信息；maxTokensField控制长度字段用max_completion_tokens还是max_tokens。推理模型报developer角色不认识时，再把supportsDeveloperRole和supportsReasoningEffort设成false，pi 会改用system消息。Ollama、vLLM、SGLang 这类服务最常踩这几个坑。

apiKey 的 3 种写法

apiKey和headers都支持下面三种格式：

• "!security find-generic-password -ws 'anthropic'"：以!开头会执行这条命令，用输出当密钥。适合密钥锁在钥匙串、密码管理器里，不落在配置文件中。
• "$ANTHROPIC_API_KEY"：取同名环境变量的值。适合密钥已经通过 CI 或 shell 环境注入的场景。
• "sk-..."：字面值原样使用。适合临时调试，别提交到代码库。

验证：从模型列表到一次真实调用

打开/model，新配置会立刻生效，你的模型出现在选择列表里。

代码里同样可以按provider和id找到刚配的模型：

const model = modelRuntime.find("ollama", "llama3.1:8b"); await session.setModel(model); await session.prompt("介绍一下你自己");

找到并切换成功，说明从配置到调用的整条链路已经通了。

接下来可以做什么

• 完整字段、合并规则、思考级别映射，见模型文档packages/coding-agent/docs/models.md。
• 想在 GPU 机器上自动拉起 vLLM，可以看 部署脚本 目录，里面有model_run.sh、pod_setup.sh等工具。
• 模型接进来之后，试试给它加reasoning: true或调整contextWindow，行为会立刻不同。

【免费下载链接】piAI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI项目地址: https://gitcode.com/GitHub_Trending/pi/pi