自定义模型供应商

这是什么

千手大师把所有大模型接入统一为「流适配器」模式：每个兼容层负责把第三方 API 的请求与流式响应 转换成内部格式，上游的查询引擎、工具调用与消息渲染完全无感。因此支持一个供应商的门槛很低—— 接口兼容即可用。

provider 选择优先级（高到低）：

settings.json 的 modelType 参数
  > QS_USE_BEDROCK / QS_USE_VERTEX / QS_USE_FOUNDRY
  > QS_USE_OPENAI / QS_USE_GEMINI / QS_USE_GROK
  > 默认 firstParty

前置条件

• 已安装千手大师（qsdashi，英文别名 qs-master）。
• 目标供应商的 API key（以及自建端点时的 base URL）。
• 如需写入 settings.json 持久生效，确保对用户配置目录有写权限。
• 环境变量方式生效时，需在启动 qsdashi 的同一 shell 中导出。

启用与切换

有三种方式，可任选：

Anthropic Compatible      # 自建 Anthropic 协议端点 → modelType: anthropic
OpenAI Compatible         # Ollama / DeepSeek / vLLM / One API → modelType: openai
China LLM Providers       # DeepSeek / Zhipu GLM / Qwen / MiMo → modelType: openai
ChatGPT account           # ChatGPT 订阅账号
Gemini API                # Google Gemini → modelType: gemini
Claude account            # Claude 订阅
Anthropic Console         # Console 账户按量计费
3rd-party platform        # Bedrock / Foundry / Vertex

/provider            # 显示当前 provider
/provider openai     # 切换到 OpenAI 兼容层
/provider unset      # 清除 modelType 与所有 QS_USE_* 变量，回退到环境变量

QS_USE_OPENAI=1 \
OPENAI_BASE_URL=http://localhost:11434/v1 \
OPENAI_API_KEY=ollama \
OPENAI_MODEL=qwen3-coder \
qsdashi

配置

OpenAI 兼容层（QS_USE_OPENAI=1 启用）

模型映射优先级：OPENAI_MODEL > OPENAI_DEFAULT_{FAMILY}_MODEL > QS_DEFAULT_{FAMILY}_MODEL（向后兼容） > 内置默认映射表 > 原样透传。

Gemini 兼容层（QS_USE_GEMINI=1 启用）

模型映射优先级：GEMINI_MODEL > GEMINI_DEFAULT_{FAMILY}_MODEL > QS_DEFAULT_{FAMILY}_MODEL > 原样。若模型名能识别出 family（含 sonnet / opus / haiku）但以上都未配置，会直接抛出错误。

Grok 兼容层（QS_USE_GROK=1 启用）

云平台 provider（仅环境变量控制）

provider 注册表（providers.json）

src/services/providerRegistry/ 提供了文件化的 provider 配置机制： 从 ~/.claude/providers.json 读取一个 ProviderConfig 数组并校验， 与内置默认项按 id 合并（用户项覆盖同名默认项）。内置默认项为 cerebras、groq、qwen、deepseek。 switchProvider(id) 会计算激活某个 OpenAI 兼容 provider 所需的环境变量 （QS_USE_OPENAI=1、OPENAI_BASE_URL、OPENAI_MODEL）， 但它不修改 process.env，需要用户自行写入 shell 配置。

常用命令与参数

别名：/api 等价于 /provider。有效值集合为 anthropic, openai, gemini, grok, bedrock, vertex, foundry, unset。

实战示例

接入本地 Ollama（OpenAI 兼容）：

QS_USE_OPENAI=1 \
OPENAI_BASE_URL=http://localhost:11434/v1 \
OPENAI_API_KEY=ollama \
OPENAI_MODEL=qwen3-coder \
qsdashi

接入 DeepSeek，并显式开启思考模式：

QS_USE_OPENAI=1 \
OPENAI_BASE_URL=https://api.deepseek.com/v1 \
OPENAI_API_KEY=sk-your-deepseek-key \
OPENAI_MODEL=deepseek-reasoner \
OPENAI_ENABLE_THINKING=1 \
qsdashi

用 settings.json 持久配置 Gemini：

{
  "modelType": "gemini",
  "env": {
    "GEMINI_API_KEY": "your-key",
    "GEMINI_DEFAULT_SONNET_MODEL": "gemini-2.5-flash",
    "GEMINI_DEFAULT_OPUS_MODEL": "gemini-2.5-pro"
  }
}

在会话中查看与切换 provider：

/provider
# Current API provider: firstParty
/provider openai
# API provider set to openai.

常见问题排错