#选择模型

本页面是 Pi 官方文档 的中文翻译。仅供学习参考。

对于内置 Provider，先运行 /login，再用 /model 选择模型。只有当 Pi 尚未包含你需要的 Provider 或端点时，才使用自定义模型配置。

#选择连接方式

在模型目录中浏览当前的 Provider、模型 ID、能力、上下文上限和定价。Pi 以内置目录启动，也可以叠加来自 pi.dev 的更新目录数据。缓存的目录数据离线也可用；运行 pi update --models 强制刷新。

#认证

运行 /login 并选择一个 Provider。Pi 把凭证存储在 auth.json 中。运行 /logout 可以删除某个 Provider 的已存凭证。

你也可以通过 Provider 的环境变量提供 API Key。这在 CI 等不希望 Pi 写入凭证的环境中很有用。Providers列出了这些变量和 Provider 特定设置。

配置了多个凭证来源时，Pi 的优先顺序是：运行时 --api-key、已存的 auth.json 凭证、models.json 中的 apiKey，最后才是 Provider 的环境变量或环境中的云凭证。Provider 扩展可以定义自己的认证行为。

请对 auth.json 和任何含凭证的命令保密。在你信任某个项目之后，项目的设置和扩展可以在 Pi 进程内执行。从不可信目录加载配置之前，请阅读安全。

#选择模型

运行 /model 搜索可用模型。选择器显示对应 Provider 已有可用认证的模型。在某个模型上按 Ctrl+S 可把它保存为新会话的默认模型。

运行 /thinking 选择当前模型的 thinking level。在其中按 Ctrl+S 保存启动级别。Pi 只提供所选模型支持的级别。

Ctrl+P 在可用模型间循环。用 /scoped-models 控制该循环并保存选择，也可以通过设置配置模型匹配模式。

会话会记录模型和 thinking level 的变更。恢复会话时会恢复它们，但不会改变新会话的默认值。

#连接本地模型

Pi 直接集成 llama.cpp router。Router 会发现 GGUF 文件并按需加载模型。Pi 的 /llama 命令管理 router，/model 选择它已加载的模型。

服务器启动、模型布局、下载和连接排查见使用 llama.cpp 运行本地模型。

对于 Ollama、LM Studio、vLLM、SGLang 和其他兼容服务器，请在 models.json 中配置兼容端点。

#配置兼容端点

当某个端点使用 Pi 已支持的 API 时，使用 models.json。这包括大多数 Ollama、LM Studio、vLLM、SGLang 和代理部署。

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

这个占位 Key 让模型对 Pi 可用；Ollama 会忽略它。对于需要认证的端点，apiKey 和 header 值可以使用 $NAME 或 ${NAME} 环境变量插值、字面量，或以 !command 开头。models.json 中的命令在请求时运行，Pi 不会缓存结果。

打开 /model 会重新加载该文件。models 条目会添加或替换该 Provider 上同 ID 的模型。用 modelOverrides 修改已有内置或扩展提供的模型的元数据，而不替换该 Provider 的模型列表。未知的 override ID 会被忽略。

#描述模型输入和缓存

用 inputLimits.images.resize 控制 Pi 在把新图片附件、read 结果和工具结果图片存入对话历史之前如何编码它们：

{
  "id": "vision-model",
  "input": ["text", "image"],
  "inputLimits": {
    "images": {
      "resize": {
        "maxWidth": 1568,
        "maxHeight": 1568,
        "maxBytes": 524288,
        "jpegQuality": 75
      }
    }
  }
}

maxBytes 限制 base64 编码后的载荷。省略的 resize 字段使用保守默认值：2000 × 2000 像素、编码后 4.5 MiB、JPEG 质量 80。图片只编码一次；更换模型不会重写历史图片。目录也可以用 inputLimits.maxRequestBytes、images.maxPerMessage 和 images.maxPerRequest 描述请求的硬限制，但 Pi 目前还不会据此重写或拒绝历史。

用 promptCache 声明 Provider 对 short 或 long 保留层级尽力而为的缓存时长（秒）：

{ "id": "claude-sonnet-5", "promptCache": { "short": 300, "long": 3600 } }

在公布的区间中选择保守的一端。当前层级没有时长数据的模型不具备缓存预热资格。modelOverrides 条目可以为内置或扩展模型设置 inputLimits 或 promptCache，包括通过已验证代理访问的模型。见 cacheWarming。

兼容性设置应当描述端点请求或响应行为中已验证的差异。不要仅因为某个端点宣称兼容 OpenAI 或 Anthropic 就开启这些设置。

#使用分类器模型

分类器模型不用于对话。它们回答关于 JSON 状态的带类型问题：从若干选项中选一个、回答是否，或给出分数，每项都带概率。Pi 通过这些 Provider 提供 TypeSafe 的 Jev 模型，并通过 Workers AI 提供 Cloudflare 的 Clef 和 Clef Flash 模型：

llama.cpp router 上的 chat 模型也会列为分类器模型。

分类器模型不会出现在 /model 中。模型通过 codemode 工具到达它们；除非某个 MCP 服务器打开了它，否则它是关闭的。在设置中用 "defaultTools": ["+codemode"] 启用。脚本随后用 models.getAvailableOfType("classifier") 列出分类器模型，并调用 models.classify(model, { state, questions })：

const jev = await models.getModelOfType('classifier', 'typesafe', 'jev-latest');
const result = await models.classify(jev, {
  state: { message: 'The change works, thanks.' },
  questions: {
    approved: {
      type: 'bool',
      instructions: 'Does the user approve of the result?',
      criteria: { true: 'Approval', false: 'No approval' },
    },
  },
});
return result.answers;

Codemode 描述了问题和答案的类型。

当服务报告 Token 数时（所有 System One 服务都会），result.usage 会带上它们及其费用。Pi 把脚本的分类器调用用量加到 codemode 工具结果上，因此会计入页脚和 /session 的会话费用。费用使用模型目录中的价格；没有价格的模型（例如 TypeSafe 直接的 jev-latest）报告 Token 但不计费。

扩展通过 ctx.modelRegistry.classify() 调用分类器，不经过 codemode。虚拟模型可以用它们来路由请求；见 jev-router.ts 示例。

#使用图片模型

图片模型根据 Prompt 和可选的输入图片生成图片。Pi 把 OpenRouter 的图片模型（例如 google/gemini-2.5-flash-image 和 black-forest-labs/flux.2-pro）列在 openrouter Provider 下；它们使用与聊天模型相同的 OPENROUTER_API_KEY 或 /login 凭证。

和分类器模型一样，图片模型不会出现在 /model 中。模型通过 codemode 工具到达它们。脚本用 models.getAvailableOfType("image") 列出它们，并调用 models.generateImages(model, { input })。结果的 output 保存 base64 图片块，image() 把它们附加到 codemode 结果上，模型就能看到：

const painter = await models.getModelOfType('image', 'openrouter', 'google/gemini-2.5-flash-image');
const result = await models.generateImages(painter, {
  input: [{ type: 'text', text: 'A red fox in the snow, watercolor' }],
});
if (result.stopReason !== 'stop') return result.errorMessage;
for (const block of result.output) if (block.type === 'image') image(block);

input 也可以包含 { type: "image", data, mimeType } 块，用于编辑或作为参考。Pi 把脚本的图片调用用量加到 codemode 工具结果上，和分类器调用一样。生成的图片不会保存到磁盘。Codemode 描述完整 API。

扩展通过 ctx.modelRegistry.generateImages() 生成图片，不经过 codemode。

#添加自定义 Provider

当 Provider 需要自定义流式处理、模型发现或认证行为时，使用扩展。扩展工作流见自定义 Provider。

#排查问题

#模型不出现

确认它的 Provider 已有可用认证。自定义模型可以从 models.json 加载，但在 Pi 能解析凭证之前，它们不会出现在 /model 中。对于 llama.cpp，只显示 router 当前已加载的模型。

#认证只在一个 Shell 中生效

检查该 Key 是否来自环境变量而不是 auth.json。环境变量必须存在于启动 Pi 的那个进程中。

#在远程机器上登录会打开浏览器

如果 Provider 支持无头认证流程，请使用它。有些 Provider 允许你把最终的跳转 URL 或授权码粘贴回 Pi。见以交互方式认证。

#兼容端点拒绝请求

检查它在 models.json 中的 API 类型和兼容性设置。上游服务器必须支持相应的请求字段和行为。

法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。