戰(zhàn)：通過 models.json 注冊(cè)自建端點(diǎn)、微調(diào)模型與代理網(wǎng)關(guān))
人工智能AI Agent代碼智能體Agent 編排CLIAI 應(yīng)用【免費(fèi)下載鏈接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture項(xiàng)目地址https://gitcode.com/gh_mirrors/gs/gsd-2點(diǎn)擊查看免費(fèi)下載本篇技術(shù)指南以 GSD 項(xiàng)目GitHub 加速計(jì)劃 / gsd-2一個(gè)面向長(zhǎng)期自主運(yùn)行的元提示、上下文工程與規(guī)范驅(qū)動(dòng)開發(fā)系統(tǒng)的官方文檔為基礎(chǔ)系統(tǒng)講解如何通過~/.gsd/agent/models.json將默認(rèn)模型注冊(cè)表之外的模型接入 GSD——包括自托管推理端點(diǎn)Ollama、vLLM、LM Studio、微調(diào)模型、代理網(wǎng)關(guān)LiteLLM、OpenRouter、Vercel AI Gateway以及新發(fā)布的商業(yè)模型。讀完本文你將掌握 models.json 的完整配置語(yǔ)法、API Key 的三種取值方式、OpenAI 兼容性開關(guān)的逐項(xiàng)含義、Provider 級(jí)與模型級(jí)覆蓋語(yǔ)義以及成本追蹤與社區(qū)擴(kuò)展的接入方法。配置入口models.json 的位置、加載時(shí)機(jī)與優(yōu)先級(jí)GSD 通過~/.gsd/agent/models.json加載自定義模型與 Provider其解析邏輯實(shí)現(xiàn)在 models-resolver.ts 中。官方文檔給出的查找順序?yàn)閪/.gsd/agent/models.json主路徑~/.pi/agent/models.json回退路徑面向從 PI 平滑遷移/開發(fā)場(chǎng)景從源碼看實(shí)際解析邏輯比文檔描述更細(xì)resolveModelsJsonPath()會(huì)依次檢查兩個(gè)路徑是否存在——若 GSD 路徑存在則直接返回否則若 PI 路徑存在則返回 PI 路徑兩者都不存在時(shí)返回 GSD 路徑該文件將被創(chuàng)建。文件頭注釋還揭示了三態(tài)合并語(yǔ)義當(dāng)兩個(gè)文件同時(shí)存在時(shí)兩個(gè)文件會(huì)被合并且 GSD 文件優(yōu)先級(jí)更高。文件在每次打開/model時(shí)重新加載會(huì)話中途編輯無(wú)需重啟。這一點(diǎn)也體現(xiàn)在 preferences-models.ts 的實(shí)現(xiàn)中它以輕量 JSON 解析直接讀取 models.json保持與resolveModelsJsonPath()一致的雙路徑回退并且格式錯(cuò)誤的 models.json 不會(huì)阻斷會(huì)話啟動(dòng)——該模塊顯式忽略解析異常。同理doctor-providers.ts 在健康檢查中對(duì)損壞的 models.json 也不會(huì)報(bào)錯(cuò)?；窘Y(jié)構(gòu)Provider 與 Model 兩層模型models.json 采用Provider 容器 Model 列表的兩層結(jié)構(gòu){ providers: { my-provider: { baseUrl: https://my-endpoint.example.com/v1, apiKey: MY_PROVIDER_API_KEY, api: openai-completions, models: [ { id: model-id-here, name: Friendly Model Name, reasoning: false, input: [text], contextWindow: 128000, maxTokens: 16384, cost: { input: 0.15, output: 0.60, cacheRead: 0.015, cacheWrite: 0.19 } } ] } } }最小示例接入本地模型對(duì)于本地模型Ollama、LM Studio、vLLM每個(gè)模型只需要id一個(gè)字段{ providers: { ollama: { baseUrl: http://localhost:11434/v1, api: openai-completions, apiKey: ollama, models: [ { id: llama3.1:8b }, { id: qwen2.5-coder:7b } ] } } }apiKey字段在 JSON 語(yǔ)法上必須存在但 Ollama 會(huì)忽略它的值所以任意字符串都可以。/model與--list-models均按模型id列出條目配置的name用于模型匹配--model模式匹配以及模型詳情/狀態(tài)文本展示。支持的 API 類型api字段決定 GSD 以何種協(xié)議與端點(diǎn)通信可在 Provider 層設(shè)置該 Provider 下所有模型的默認(rèn)值也可在模型層覆蓋API說明openai-completionsOpenAI Chat Completions兼容性最好本地服務(wù)首選openai-responsesOpenAI Responses APIanthropic-messagesAnthropic Messages APIgoogle-generative-aiGoogle Generative AI模型配置字段參考字段必填默認(rèn)值說明id是—模型標(biāo)識(shí)符實(shí)際傳給 API 的模型名name否id人類可讀的模型標(biāo)簽用于--model匹配與狀態(tài)展示api否Provider 的api覆蓋 Provider 層的 API 類型reasoning否false是否支持?jǐn)U展思考extended thinkinginput否[text]輸入類型[text]或[text, image]contextWindow否128000上下文窗口大小token 數(shù)maxTokens否16384最大輸出 token 數(shù)cost否全零每百萬(wàn) token 成本{input, output, cacheRead, cacheWrite}compat否Provider 的compatOpenAI 兼容性覆蓋與 Provider 層compat合并生效關(guān)于reasoning: true的模型從 openai-completions.ts 的實(shí)現(xiàn)看系統(tǒng)提示詞的角色選擇與思考參數(shù)的注入都由reasoning與compat共同決定見下文。API Key 解析環(huán)境變量、字面量與占位值apiKey字段支持三種取值方式GSD 會(huì)自動(dòng)分辨環(huán)境變量名OPENROUTER_API_KEY— GSD 自動(dòng)解析同名環(huán)境變量的值字面量sk-abc123...— 直接使用該字符串占位值not-needed— 供無(wú)需鑒權(quán)的本地服務(wù)使用。更完整的取值機(jī)制見 docs/user-docs/custom-models.md其中apiKey與headers的取值實(shí)際支持三種格式比 gitbook 版文檔多出一種Shell 命令格式Shell 命令以!開頭執(zhí)行命令并取 stdout 作為值例如從系統(tǒng)鑰匙串或密碼管理器讀取憑據(jù)apiKey: !security find-generic-password -ws anthropic apiKey: !op read op://vault/item/credential該機(jī)制有命令白名單保護(hù)只有以pass、op、aws、gcloud、vault、security、gpg、bw、gopass、lpass開頭的命令允許執(zhí)行其余命令被攔截且值解析為undefined同時(shí)向 stderr 寫入警告命令參數(shù)中禁止出現(xiàn);、|、、反引號(hào)、$、、等 Shell 運(yùn)算符以防止注入。若使用白名單之外的憑據(jù)工具可在全局設(shè)置~/.gsd/agent/settings.json中通過allowedCommandPrefixes整體替換默認(rèn)白名單需自行包含仍要保留的默認(rèn)項(xiàng){ allowedCommandPrefixes: [pass, op, sops, doppler, mycli] }也可以設(shè)置逗號(hào)分隔的環(huán)境變量GSD_ALLOWED_COMMAND_PREFIXES其優(yōu)先級(jí)高于 settings.jsonexport GSD_ALLOWED_COMMAND_PREFIXESpass,op,sops,doppler注意該設(shè)置是全局限定的項(xiàng)目級(jí)project/.gsd/settings.json無(wú)法覆蓋命令白名單——這是為了防止克隆倉(cāng)庫(kù)提升命令執(zhí)行權(quán)限。從源碼側(cè)印證doctor-providers.ts 會(huì)把認(rèn)證來(lái)源歸類為auth.json、env、models.json、none四類doctor-providers.test.ts 中的測(cè)試也驗(yàn)證了 models.json 中的 apiKey 可以滿足自定義 Provider 的鑒權(quán)檢查。這意味著配置了有效 apiKey 的自定義 Provider 不會(huì)觸發(fā)儀表盤的健康告警。Compatibility FlagsOpenAI 兼容性開關(guān)本地服務(wù)與非標(biāo)準(zhǔn)服務(wù)器往往需要兼容性調(diào)整compat字段就是為此設(shè)計(jì)的{ compat: { supportsDeveloperRole: false, supportsReasoningEffort: false, stripReasoningContent: true, supportsUsageInStreaming: false, thinkingFormat: qwen } }compat可以放在 Provider 層對(duì)該 Provider 下所有模型生效也可以放在模型層僅覆蓋該模型。兩層同時(shí)設(shè)置時(shí)會(huì)合并模型層優(yōu)先。開關(guān)默認(rèn)值作用supportsDeveloperRoletrue服務(wù)器不支持developer消息角色時(shí)設(shè)為falsesupportsReasoningEfforttrue服務(wù)器不支持reasoning_effort參數(shù)時(shí)設(shè)為falsestripReasoningContentfalse設(shè)為true時(shí)從外發(fā)歷史中剝離回放的 assistantreasoning_content字段部分 vLLM/TensorRT-LLM 端點(diǎn)否則會(huì)返回 400 錯(cuò)誤supportsUsageInStreamingtrue流式響應(yīng)不包含 token 用量時(shí)設(shè)為falsethinkingFormat—qwen使用 Qwen 思考模式qwen-chat-template使用聊天模板變體背后的源碼機(jī)制這些開關(guān)在 pi-ai 的 OpenAI 兼容層中有完整實(shí)現(xiàn)。OpenAICompletionsCompat接口定義于 types.ts除上述開關(guān)外還包括maxTokensFieldmax_completion_tokens或max_tokens、requiresToolResultName、requiresAssistantAfterToolResult、requiresThinkingAsText、supportsStrictMode、reasoningEffortMap等且多數(shù)開關(guān)標(biāo)注為從 URL 自動(dòng)探測(cè)默認(rèn)值。關(guān)鍵行為對(duì)應(yīng)關(guān)系如下supportsDeveloperRole在 openai-completions.ts 的convertMessages()中系統(tǒng)提示詞的角色由model.reasoning compat.supportsDeveloperRole決定——推理模型且服務(wù)器支持時(shí)才使用developer角色否則回退為system消息。這與 docs/user-docs/custom-models.md 的說明一致不支持developer角色的服務(wù)器如 Ollama 等本地端點(diǎn)應(yīng)設(shè)supportsDeveloperRole: false讓 GSD 用system消息發(fā)送系統(tǒng)提示詞。stripReasoningContent同樣在convertMessages()中實(shí)現(xiàn)啟用時(shí)會(huì)在外發(fā)消息轉(zhuǎn)換階段剝離回放的推理字段。單元測(cè)試 openai-completions.test.ts 用一條帶thinkingSignature: reasoning_content的 assistant 消息驗(yàn)證了兩種行為啟用后reasoning_content字段被剝離值為undefined未啟用時(shí)則原樣透?jìng)?。thinkingFormat與思考參數(shù)請(qǐng)求構(gòu)造邏輯中zai與qwen格式對(duì)推理模型使用頂層enable_thinking: boolean值由 reasoningEffort 決定OpenAI 風(fēng)格默認(rèn)openai則通過reasoning_effort參數(shù)注入并可經(jīng)reasoningEffortMap將 GSD 思考級(jí)別映射為 Provider 特定的取值。qwen使用頂層enable_thinking而qwen-chat-template針對(duì)需要chat_template_kwargs.enable_thinking的本地 Qwen 兼容服務(wù)器。內(nèi)置模型注冊(cè)表 custom.ts 中多個(gè) Qwen/Z.ai 系列條目即使用thinkingFormat: qwen/zai配合supportsDeveloperRole: false。自定義 Headers為代理補(bǔ)充額外請(qǐng)求頭需要額外請(qǐng)求頭的代理場(chǎng)景可在 Provider 層設(shè)置headers{ providers: { litellm-proxy: { baseUrl: https://litellm.example.com/v1, apiKey: MY_API_KEY, api: openai-completions, headers: { x-custom-header: value }, models: [...] } } }headers的取值方式與apiKey完全一致同樣支持環(huán)境變量名、字面量與 Shell 命令三種格式。例如通過 Portkey 網(wǎng)關(guān)路由 Anthropic 請(qǐng)求時(shí)可以這樣寫headers: { x-portkey-api-key: PORTKEY_API_KEY, x-secret: !op read op://vault/item/secret }另外Provider 層還有authHeader字段設(shè)為true時(shí) GSD 自動(dòng)追加Authorization: Bearer apiKey請(qǐng)求頭。Model Overrides按模型覆蓋內(nèi)置模型無(wú)需重定義整個(gè)模型modelOverrides允許在不重寫 Provider 全部模型列表的前提下精細(xì)化定制某個(gè)內(nèi)置模型的設(shè)置{ providers: { openrouter: { modelOverrides: { anthropic/claude-sonnet-4: { compat: { openRouterRouting: { only: [amazon-bedrock] } } } } } } }modelOverrides支持按模型覆蓋以下字段name、reasoning、input、cost支持部分覆蓋、contextWindow、maxTokens、headers、compat。行為語(yǔ)義如下覆蓋只作用于內(nèi)置 Provider 的模型未知模型 ID 會(huì)被忽略可同時(shí)使用 Provider 層的baseUrl/headers與modelOverrides若 Provider 同時(shí)定義了models數(shù)組自定義模型在內(nèi)置覆蓋之后合并——id相同的自定義模型會(huì)替換被覆蓋的內(nèi)置條目。openRouterRouting與vercelGatewayRouting在 types.ts 中都有類型定義二者結(jié)構(gòu)一致only指定僅路由到的 Provider 列表order指定嘗試順序。請(qǐng)求構(gòu)造邏輯中當(dāng)baseUrl指向 openrouter.ai 且模型帶openRouterRouting時(shí)路由偏好以provider字段傳給 OpenRouter指向 Vercel AI Gateway 時(shí)則以providerOptions.gateway傳遞。Vercel 網(wǎng)關(guān)示例如路由 Kimi K2.5 經(jīng)由 Fireworks/Novitacompat: { vercelGatewayRouting: { only: [fireworks, novita], order: [fireworks, novita] } }覆蓋內(nèi)置 Provider將流量重定向到代理若只是想把某個(gè)內(nèi)置 Provider 的流量經(jīng)代理轉(zhuǎn)發(fā)不必重定義其模型列表——直接覆蓋baseUrl即可{ providers: { anthropic: { baseUrl: https://my-proxy.example.com/v1 } } }此時(shí)內(nèi)置 Anthropic 模型全部保留可用原有的 OAuth 或 API Key 鑒權(quán)繼續(xù)生效。若要同時(shí)向內(nèi)置 Provider 合并自定義模型則需補(bǔ)上models數(shù)組{ providers: { anthropic: { baseUrl: https://my-proxy.example.com/v1, apiKey: ANTHROPIC_API_KEY, api: anthropic-messages, models: [...] } } }合并語(yǔ)義與 docs/user-docs/custom-models.md 中 Overriding Built-in Providers 章節(jié)一致內(nèi)置模型保留自定義模型按id在 Provider 內(nèi) upsertid與內(nèi)置模型相同的自定義模型替換內(nèi)置條目全新id則追加到內(nèi)置模型旁。Cost Tracking讓自定義模型成本不再顯示為 $0.00自定義模型默認(rèn)不產(chǎn)生成本數(shù)據(jù)——沒有cost字段時(shí)成本追蹤顯示 $0.00這是預(yù)期默認(rèn)行為。需要準(zhǔn)確成本統(tǒng)計(jì)時(shí)按每百萬(wàn) token添加cost字段cost: { input: 0.15, output: 0.60, cacheRead: 0.015, cacheWrite: 0.19 }cost同樣支持部分覆蓋如僅在modelOverrides中覆蓋input與output。本地模型成本為零時(shí)可顯式寫全零與內(nèi)置注冊(cè)表中各模型的成本結(jié)構(gòu)保持同構(gòu)。社區(qū)擴(kuò)展為未內(nèi)置 Provider 提供完整支持對(duì)于 GSD 未內(nèi)置的 Provider社區(qū)擴(kuò)展可提供完整的 Provider 支持。例如阿里云 DashScopeQwen3、GLM-5 等通過pi-dashscope擴(kuò)展安裝gsd install npm:pi-dashscope擴(kuò)展機(jī)制與 extensions 生態(tài)相關(guān)更多說明可參考 docs/dev/extending-pi/ 與 docs/extension-sdk/。常見排障與最佳實(shí)踐小結(jié)400 錯(cuò)誤來(lái)自推理內(nèi)容回放若接入 vLLM/TensorRT-LLM 端點(diǎn)時(shí)多輪對(duì)話請(qǐng)求返回 400優(yōu)先檢查compat.stripReasoningContent: true參考 docs/user-docs/custom-models.md 的說明與 openai-completions.test.ts 的驗(yàn)證用例。角色錯(cuò)誤本地服務(wù)器不支持developer角色時(shí)設(shè)置compat.supportsDeveloperRole: false同時(shí)不支持reasoning_effort時(shí)再設(shè)置supportsReasoningEffort: falseOllama 即屬此類詳見 docs/user-docs/providers.md 中的 Ollama 配置示例。憑據(jù)來(lái)源可觀測(cè)gsd doctor的健康檢查會(huì)報(bào)告每個(gè)自定義 Provider 的認(rèn)證來(lái)源models.json/env/auth.json可通過 doctor-providers.ts 的實(shí)現(xiàn)了解其判定邏輯。配置即時(shí)生效修改 models.json 后打開/model即可重載無(wú)需重啟 GSD格式錯(cuò)誤不會(huì)阻斷啟動(dòng)可放心迭代。綜合來(lái)看models.json 是 GSD 接入任意模型的關(guān)鍵擴(kuò)展點(diǎn)無(wú)論是本地 Ollama/vLLM/LM Studio、私有微調(diào)模型還是 OpenRouter、Vercel AI Gateway 等代理網(wǎng)關(guān)都可在一份 JSON 中完成注冊(cè)、鑒權(quán)、兼容性適配與成本配置并在/model中立即切換使用。贊分享人工智能AI Agent代碼智能體Agent 編排CLIAI 應(yīng)用【免費(fèi)下載鏈接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture項(xiàng)目地址https://gitcode.com/gh_mirrors/gs/gsd-2點(diǎn)擊查看免費(fèi)下載相關(guān)推薦MLflow Gateway 插件 Provider 實(shí)戰(zhàn)通過 Python Entry Point 擴(kuò)展自定義模型端點(diǎn)MLflow Gateway 插件 Provider 實(shí)戰(zhàn)通過 Python Entry Point 擴(kuò)展自定義模型端點(diǎn) 導(dǎo)讀 MLflow GatewayMLOpsLLMOps人工智能大模型模型評(píng)測(cè)LLM 網(wǎng)關(guān)可觀測(cè)性mpv Lua 腳本完整指南5 個(gè)腳本快速搞定追劇、裁剪、音量與置頂mpv Lua 腳本完整指南5 個(gè)腳本快速搞定追劇、裁剪、音量與置頂 看老電影上下黑邊占掉小半個(gè)屏追到第 5 集播放器卻停在列表結(jié)束電視劇廣告炸耳音視頻視頻音頻Flue 模型接入完全指南useModel 聲明、調(diào)參與 Provider 注冊(cè)實(shí)戰(zhàn)Flue 模型接入完全指南useModel 聲明、調(diào)參與 Provider 注冊(cè)實(shí)戰(zhàn) 每個(gè) Flue Agent 在同一時(shí)刻只由一個(gè) LLM 驅(qū)動(dòng)而這個(gè)模型人工智能大模型AI AgentAgent 框架工具調(diào)用Agent 沙箱MCP Clients上一篇告別聊天記錄丟失WeChatMsg 微信聊天記錄導(dǎo)出與永久保存完整指南下一篇如何用SubtitleEdit完成字幕編輯時(shí)間軸校準(zhǔn)、批量轉(zhuǎn)換與OCR實(shí)戰(zhàn)全攻略創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 GSD 自定義模型與 Provider 接入實(shí)戰(zhàn)：通過 models.json 注冊(cè)自建端點(diǎn)、微調(diào)模型與代理網(wǎng)關(guān)
人工智能AI Agent代碼智能體Agent 編排CLIAI 應(yīng)用【免費(fèi)下載鏈接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture項(xiàng)目地址https://gitcode.com/gh_mirrors/gs/gsd-2點(diǎn)擊查看免費(fèi)下載本篇技術(shù)指南以 GSD 項(xiàng)目GitHub 加速計(jì)劃 / gsd-2一個(gè)面向長(zhǎng)期自主運(yùn)行的元提示、上下文工程與規(guī)范驅(qū)動(dòng)開發(fā)系統(tǒng)的官方文檔為基礎(chǔ)系統(tǒng)講解如何通過~/.gsd/agent/models.json將默認(rèn)模型注冊(cè)表之外的模型接入 GSD——包括自托管推理端點(diǎn)Ollama、vLLM、LM Studio、微調(diào)模型、代理網(wǎng)關(guān)LiteLLM、OpenRouter、Vercel AI Gateway以及新發(fā)布的商業(yè)模型。讀完本文你將掌握 models.json 的完整配置語(yǔ)法、API Key 的三種取值方式、OpenAI 兼容性開關(guān)的逐項(xiàng)含義、Provider 級(jí)與模型級(jí)覆蓋語(yǔ)義以及成本追蹤與社區(qū)擴(kuò)展的接入方法。配置入口models.json 的位置、加載時(shí)機(jī)與優(yōu)先級(jí)GSD 通過~/.gsd/agent/models.json加載自定義模型與 Provider其解析邏輯實(shí)現(xiàn)在 models-resolver.ts 中。官方文檔給出的查找順序?yàn)閪/.gsd/agent/models.json主路徑~/.pi/agent/models.json回退路徑面向從 PI 平滑遷移/開發(fā)場(chǎng)景從源碼看實(shí)際解析邏輯比文檔描述更細(xì)resolveModelsJsonPath()會(huì)依次檢查兩個(gè)路徑是否存在——若 GSD 路徑存在則直接返回否則若 PI 路徑存在則返回 PI 路徑兩者都不存在時(shí)返回 GSD 路徑該文件將被創(chuàng)建。文件頭注釋還揭示了三態(tài)合并語(yǔ)義當(dāng)兩個(gè)文件同時(shí)存在時(shí)兩個(gè)文件會(huì)被合并且 GSD 文件優(yōu)先級(jí)更高。文件在每次打開/model時(shí)重新加載會(huì)話中途編輯無(wú)需重啟。這一點(diǎn)也體現(xiàn)在 preferences-models.ts 的實(shí)現(xiàn)中它以輕量 JSON 解析直接讀取 models.json保持與resolveModelsJsonPath()一致的雙路徑回退并且格式錯(cuò)誤的 models.json 不會(huì)阻斷會(huì)話啟動(dòng)——該模塊顯式忽略解析異常。同理doctor-providers.ts 在健康檢查中對(duì)損壞的 models.json 也不會(huì)報(bào)錯(cuò)?；窘Y(jié)構(gòu)Provider 與 Model 兩層模型models.json 采用Provider 容器 Model 列表的兩層結(jié)構(gòu){ providers: { my-provider: { baseUrl: https://my-endpoint.example.com/v1, apiKey: MY_PROVIDER_API_KEY, api: openai-completions, models: [ { id: model-id-here, name: Friendly Model Name, reasoning: false, input: [text], contextWindow: 128000, maxTokens: 16384, cost: { input: 0.15, output: 0.60, cacheRead: 0.015, cacheWrite: 0.19 } } ] } } }最小示例接入本地模型對(duì)于本地模型Ollama、LM Studio、vLLM每個(gè)模型只需要id一個(gè)字段{ providers: { ollama: { baseUrl: http://localhost:11434/v1, api: openai-completions, apiKey: ollama, models: [ { id: llama3.1:8b }, { id: qwen2.5-coder:7b } ] } } }apiKey字段在 JSON 語(yǔ)法上必須存在但 Ollama 會(huì)忽略它的值所以任意字符串都可以。/model與--list-models均按模型id列出條目配置的name用于模型匹配--model模式匹配以及模型詳情/狀態(tài)文本展示。支持的 API 類型api字段決定 GSD 以何種協(xié)議與端點(diǎn)通信可在 Provider 層設(shè)置該 Provider 下所有模型的默認(rèn)值也可在模型層覆蓋API說明openai-completionsOpenAI Chat Completions兼容性最好本地服務(wù)首選openai-responsesOpenAI Responses APIanthropic-messagesAnthropic Messages APIgoogle-generative-aiGoogle Generative AI模型配置字段參考字段必填默認(rèn)值說明id是—模型標(biāo)識(shí)符實(shí)際傳給 API 的模型名name否id人類可讀的模型標(biāo)簽用于--model匹配與狀態(tài)展示api否Provider 的api覆蓋 Provider 層的 API 類型reasoning否false是否支持?jǐn)U展思考extended thinkinginput否[text]輸入類型[text]或[text, image]contextWindow否128000上下文窗口大小token 數(shù)maxTokens否16384最大輸出 token 數(shù)cost否全零每百萬(wàn) token 成本{input, output, cacheRead, cacheWrite}compat否Provider 的compatOpenAI 兼容性覆蓋與 Provider 層compat合并生效關(guān)于reasoning: true的模型從 openai-completions.ts 的實(shí)現(xiàn)看系統(tǒng)提示詞的角色選擇與思考參數(shù)的注入都由reasoning與compat共同決定見下文。API Key 解析環(huán)境變量、字面量與占位值apiKey字段支持三種取值方式GSD 會(huì)自動(dòng)分辨環(huán)境變量名OPENROUTER_API_KEY— GSD 自動(dòng)解析同名環(huán)境變量的值字面量sk-abc123...— 直接使用該字符串占位值not-needed— 供無(wú)需鑒權(quán)的本地服務(wù)使用。更完整的取值機(jī)制見 docs/user-docs/custom-models.md其中apiKey與headers的取值實(shí)際支持三種格式比 gitbook 版文檔多出一種Shell 命令格式Shell 命令以!開頭執(zhí)行命令并取 stdout 作為值例如從系統(tǒng)鑰匙串或密碼管理器讀取憑據(jù)apiKey: !security find-generic-password -ws anthropic apiKey: !op read op://vault/item/credential該機(jī)制有命令白名單保護(hù)只有以pass、op、aws、gcloud、vault、security、gpg、bw、gopass、lpass開頭的命令允許執(zhí)行其余命令被攔截且值解析為undefined同時(shí)向 stderr 寫入警告命令參數(shù)中禁止出現(xiàn);、|、、反引號(hào)、$、、等 Shell 運(yùn)算符以防止注入。若使用白名單之外的憑據(jù)工具可在全局設(shè)置~/.gsd/agent/settings.json中通過allowedCommandPrefixes整體替換默認(rèn)白名單需自行包含仍要保留的默認(rèn)項(xiàng){ allowedCommandPrefixes: [pass, op, sops, doppler, mycli] }也可以設(shè)置逗號(hào)分隔的環(huán)境變量GSD_ALLOWED_COMMAND_PREFIXES其優(yōu)先級(jí)高于 settings.jsonexport GSD_ALLOWED_COMMAND_PREFIXESpass,op,sops,doppler注意該設(shè)置是全局限定的項(xiàng)目級(jí)project/.gsd/settings.json無(wú)法覆蓋命令白名單——這是為了防止克隆倉(cāng)庫(kù)提升命令執(zhí)行權(quán)限。從源碼側(cè)印證doctor-providers.ts 會(huì)把認(rèn)證來(lái)源歸類為auth.json、env、models.json、none四類doctor-providers.test.ts 中的測(cè)試也驗(yàn)證了 models.json 中的 apiKey 可以滿足自定義 Provider 的鑒權(quán)檢查。這意味著配置了有效 apiKey 的自定義 Provider 不會(huì)觸發(fā)儀表盤的健康告警。Compatibility FlagsOpenAI 兼容性開關(guān)本地服務(wù)與非標(biāo)準(zhǔn)服務(wù)器往往需要兼容性調(diào)整compat字段就是為此設(shè)計(jì)的{ compat: { supportsDeveloperRole: false, supportsReasoningEffort: false, stripReasoningContent: true, supportsUsageInStreaming: false, thinkingFormat: qwen } }compat可以放在 Provider 層對(duì)該 Provider 下所有模型生效也可以放在模型層僅覆蓋該模型。兩層同時(shí)設(shè)置時(shí)會(huì)合并模型層優(yōu)先。開關(guān)默認(rèn)值作用supportsDeveloperRoletrue服務(wù)器不支持developer消息角色時(shí)設(shè)為falsesupportsReasoningEfforttrue服務(wù)器不支持reasoning_effort參數(shù)時(shí)設(shè)為falsestripReasoningContentfalse設(shè)為true時(shí)從外發(fā)歷史中剝離回放的 assistantreasoning_content字段部分 vLLM/TensorRT-LLM 端點(diǎn)否則會(huì)返回 400 錯(cuò)誤supportsUsageInStreamingtrue流式響應(yīng)不包含 token 用量時(shí)設(shè)為falsethinkingFormat—qwen使用 Qwen 思考模式qwen-chat-template使用聊天模板變體背后的源碼機(jī)制這些開關(guān)在 pi-ai 的 OpenAI 兼容層中有完整實(shí)現(xiàn)。OpenAICompletionsCompat接口定義于 types.ts除上述開關(guān)外還包括maxTokensFieldmax_completion_tokens或max_tokens、requiresToolResultName、requiresAssistantAfterToolResult、requiresThinkingAsText、supportsStrictMode、reasoningEffortMap等且多數(shù)開關(guān)標(biāo)注為從 URL 自動(dòng)探測(cè)默認(rèn)值。關(guān)鍵行為對(duì)應(yīng)關(guān)系如下supportsDeveloperRole在 openai-completions.ts 的convertMessages()中系統(tǒng)提示詞的角色由model.reasoning compat.supportsDeveloperRole決定——推理模型且服務(wù)器支持時(shí)才使用developer角色否則回退為system消息。這與 docs/user-docs/custom-models.md 的說明一致不支持developer角色的服務(wù)器如 Ollama 等本地端點(diǎn)應(yīng)設(shè)supportsDeveloperRole: false讓 GSD 用system消息發(fā)送系統(tǒng)提示詞。stripReasoningContent同樣在convertMessages()中實(shí)現(xiàn)啟用時(shí)會(huì)在外發(fā)消息轉(zhuǎn)換階段剝離回放的推理字段。單元測(cè)試 openai-completions.test.ts 用一條帶thinkingSignature: reasoning_content的 assistant 消息驗(yàn)證了兩種行為啟用后reasoning_content字段被剝離值為undefined未啟用時(shí)則原樣透?jìng)?。thinkingFormat與思考參數(shù)請(qǐng)求構(gòu)造邏輯中zai與qwen格式對(duì)推理模型使用頂層enable_thinking: boolean值由 reasoningEffort 決定OpenAI 風(fēng)格默認(rèn)openai則通過reasoning_effort參數(shù)注入并可經(jīng)reasoningEffortMap將 GSD 思考級(jí)別映射為 Provider 特定的取值。qwen使用頂層enable_thinking而qwen-chat-template針對(duì)需要chat_template_kwargs.enable_thinking的本地 Qwen 兼容服務(wù)器。內(nèi)置模型注冊(cè)表 custom.ts 中多個(gè) Qwen/Z.ai 系列條目即使用thinkingFormat: qwen/zai配合supportsDeveloperRole: false。自定義 Headers為代理補(bǔ)充額外請(qǐng)求頭需要額外請(qǐng)求頭的代理場(chǎng)景可在 Provider 層設(shè)置headers{ providers: { litellm-proxy: { baseUrl: https://litellm.example.com/v1, apiKey: MY_API_KEY, api: openai-completions, headers: { x-custom-header: value }, models: [...] } } }headers的取值方式與apiKey完全一致同樣支持環(huán)境變量名、字面量與 Shell 命令三種格式。例如通過 Portkey 網(wǎng)關(guān)路由 Anthropic 請(qǐng)求時(shí)可以這樣寫headers: { x-portkey-api-key: PORTKEY_API_KEY, x-secret: !op read op://vault/item/secret }另外Provider 層還有authHeader字段設(shè)為true時(shí) GSD 自動(dòng)追加Authorization: Bearer apiKey請(qǐng)求頭。Model Overrides按模型覆蓋內(nèi)置模型無(wú)需重定義整個(gè)模型modelOverrides允許在不重寫 Provider 全部模型列表的前提下精細(xì)化定制某個(gè)內(nèi)置模型的設(shè)置{ providers: { openrouter: { modelOverrides: { anthropic/claude-sonnet-4: { compat: { openRouterRouting: { only: [amazon-bedrock] } } } } } } }modelOverrides支持按模型覆蓋以下字段name、reasoning、input、cost支持部分覆蓋、contextWindow、maxTokens、headers、compat。行為語(yǔ)義如下覆蓋只作用于內(nèi)置 Provider 的模型未知模型 ID 會(huì)被忽略可同時(shí)使用 Provider 層的baseUrl/headers與modelOverrides若 Provider 同時(shí)定義了models數(shù)組自定義模型在內(nèi)置覆蓋之后合并——id相同的自定義模型會(huì)替換被覆蓋的內(nèi)置條目。openRouterRouting與vercelGatewayRouting在 types.ts 中都有類型定義二者結(jié)構(gòu)一致only指定僅路由到的 Provider 列表order指定嘗試順序。請(qǐng)求構(gòu)造邏輯中當(dāng)baseUrl指向 openrouter.ai 且模型帶openRouterRouting時(shí)路由偏好以provider字段傳給 OpenRouter指向 Vercel AI Gateway 時(shí)則以providerOptions.gateway傳遞。Vercel 網(wǎng)關(guān)示例如路由 Kimi K2.5 經(jīng)由 Fireworks/Novitacompat: { vercelGatewayRouting: { only: [fireworks, novita], order: [fireworks, novita] } }覆蓋內(nèi)置 Provider將流量重定向到代理若只是想把某個(gè)內(nèi)置 Provider 的流量經(jīng)代理轉(zhuǎn)發(fā)不必重定義其模型列表——直接覆蓋baseUrl即可{ providers: { anthropic: { baseUrl: https://my-proxy.example.com/v1 } } }此時(shí)內(nèi)置 Anthropic 模型全部保留可用原有的 OAuth 或 API Key 鑒權(quán)繼續(xù)生效。若要同時(shí)向內(nèi)置 Provider 合并自定義模型則需補(bǔ)上models數(shù)組{ providers: { anthropic: { baseUrl: https://my-proxy.example.com/v1, apiKey: ANTHROPIC_API_KEY, api: anthropic-messages, models: [...] } } }合并語(yǔ)義與 docs/user-docs/custom-models.md 中 Overriding Built-in Providers 章節(jié)一致內(nèi)置模型保留自定義模型按id在 Provider 內(nèi) upsertid與內(nèi)置模型相同的自定義模型替換內(nèi)置條目全新id則追加到內(nèi)置模型旁。Cost Tracking讓自定義模型成本不再顯示為 $0.00自定義模型默認(rèn)不產(chǎn)生成本數(shù)據(jù)——沒有cost字段時(shí)成本追蹤顯示 $0.00這是預(yù)期默認(rèn)行為。需要準(zhǔn)確成本統(tǒng)計(jì)時(shí)按每百萬(wàn) token添加cost字段cost: { input: 0.15, output: 0.60, cacheRead: 0.015, cacheWrite: 0.19 }cost同樣支持部分覆蓋如僅在modelOverrides中覆蓋input與output。本地模型成本為零時(shí)可顯式寫全零與內(nèi)置注冊(cè)表中各模型的成本結(jié)構(gòu)保持同構(gòu)。社區(qū)擴(kuò)展為未內(nèi)置 Provider 提供完整支持對(duì)于 GSD 未內(nèi)置的 Provider社區(qū)擴(kuò)展可提供完整的 Provider 支持。例如阿里云 DashScopeQwen3、GLM-5 等通過pi-dashscope擴(kuò)展安裝gsd install npm:pi-dashscope擴(kuò)展機(jī)制與 extensions 生態(tài)相關(guān)更多說明可參考 docs/dev/extending-pi/ 與 docs/extension-sdk/。常見排障與最佳實(shí)踐小結(jié)400 錯(cuò)誤來(lái)自推理內(nèi)容回放若接入 vLLM/TensorRT-LLM 端點(diǎn)時(shí)多輪對(duì)話請(qǐng)求返回 400優(yōu)先檢查compat.stripReasoningContent: true參考 docs/user-docs/custom-models.md 的說明與 openai-completions.test.ts 的驗(yàn)證用例。角色錯(cuò)誤本地服務(wù)器不支持developer角色時(shí)設(shè)置compat.supportsDeveloperRole: false同時(shí)不支持reasoning_effort時(shí)再設(shè)置supportsReasoningEffort: falseOllama 即屬此類詳見 docs/user-docs/providers.md 中的 Ollama 配置示例。憑據(jù)來(lái)源可觀測(cè)gsd doctor的健康檢查會(huì)報(bào)告每個(gè)自定義 Provider 的認(rèn)證來(lái)源models.json/env/auth.json可通過 doctor-providers.ts 的實(shí)現(xiàn)了解其判定邏輯。配置即時(shí)生效修改 models.json 后打開/model即可重載無(wú)需重啟 GSD格式錯(cuò)誤不會(huì)阻斷啟動(dòng)可放心迭代。綜合來(lái)看models.json 是 GSD 接入任意模型的關(guān)鍵擴(kuò)展點(diǎn)無(wú)論是本地 Ollama/vLLM/LM Studio、私有微調(diào)模型還是 OpenRouter、Vercel AI Gateway 等代理網(wǎng)關(guān)都可在一份 JSON 中完成注冊(cè)、鑒權(quán)、兼容性適配與成本配置并在/model中立即切換使用。贊分享人工智能AI Agent代碼智能體Agent 編排CLIAI 應(yīng)用【免費(fèi)下載鏈接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture項(xiàng)目地址https://gitcode.com/gh_mirrors/gs/gsd-2點(diǎn)擊查看免費(fèi)下載相關(guān)推薦MLflow Gateway 插件 Provider 實(shí)戰(zhàn)通過 Python Entry Point 擴(kuò)展自定義模型端點(diǎn)MLflow Gateway 插件 Provider 實(shí)戰(zhàn)通過 Python Entry Point 擴(kuò)展自定義模型端點(diǎn) 導(dǎo)讀 MLflow GatewayMLOpsLLMOps人工智能大模型模型評(píng)測(cè)LLM 網(wǎng)關(guān)可觀測(cè)性mpv Lua 腳本完整指南5 個(gè)腳本快速搞定追劇、裁剪、音量與置頂mpv Lua 腳本完整指南5 個(gè)腳本快速搞定追劇、裁剪、音量與置頂 看老電影上下黑邊占掉小半個(gè)屏追到第 5 集播放器卻停在列表結(jié)束電視劇廣告炸耳音視頻視頻音頻Flue 模型接入完全指南useModel 聲明、調(diào)參與 Provider 注冊(cè)實(shí)戰(zhàn)Flue 模型接入完全指南useModel 聲明、調(diào)參與 Provider 注冊(cè)實(shí)戰(zhàn) 每個(gè) Flue Agent 在同一時(shí)刻只由一個(gè) LLM 驅(qū)動(dòng)而這個(gè)模型人工智能大模型AI AgentAgent 框架工具調(diào)用Agent 沙箱MCP Clients上一篇告別聊天記錄丟失WeChatMsg 微信聊天記錄導(dǎo)出與永久保存完整指南下一篇如何用SubtitleEdit完成字幕編輯時(shí)間軸校準(zhǔn)、批量轉(zhuǎn)換與OCR實(shí)戰(zhàn)全攻略創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考