GPT4All 本地 API Server 实战指南用 OpenAI 兼容 HTTP 接口驱动本地 LLM 并接入 LocalDocs【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4all本篇技术指南基于 GPT4All 官方文档 GPT4All API Server 展开系统讲解如何在 GPT4All Chat 桌面应用中启用内置的本地 HTTP API Server、使用 cURL/PowerShell 等工具发起 OpenAI 兼容请求并结合仓库源码server.cpp深入解析各端点的请求参数校验、响应结构与 LocalDocs 检索增强RAG集成的完整机制。读完本文你可以让任何支持 OpenAI API 的客户端直接调用自己硬件上运行的模型并从 API 响应中读取 LocalDocs 检索到的参考片段。一、核心特性与定位GPT4All 提供的本地 API Server 让你在自己的硬件上通过 HTTP API 运行大语言模型。官方文档概括了三个关键特性Local Execution本地执行模型完全运行在本地硬件上保障隐私与离线可用性LocalDocs Integration本地文档集成API 调用时可从 LocalDocs 集合中检索与问题语义相关的文本片段作为上下文注入给 LLMOpenAI API CompatibilityOpenAI API 兼容现有的 OpenAI 兼容客户端和工具无需改造即可指向本地模型。从源码结构看该服务由桌面应用内的Server类实现server.h它继承自ChatLLM基于 Qt6 的QHttpServerQTcpServer构建。这意味着 API Server 与桌面 UI 共享同一个模型加载、对话上下文与 LocalDocs 数据库管线——API 请求实际上会写入并出现在服务器聊天会话中。二、激活 API Server官方文档给出的启用步骤如下打开 GPT4All Chat 桌面应用进入SettingsApplication向下滚动到Advanced高级区域勾选Enable Local API Server选项服务器默认监听4891端口可通过API Server Port设置项改用其他端口。这一操作在源码中有明确对应ApplicationSettings.qml 中定义了Enable Local API Server复选框直接绑定到MySettings.serverChat属性旁边的API Server Port设置项帮助文案为 The port to use for the local server. Requires restart.说明修改端口需要重启应用才能生效。在 mysettings.cpp 中可以看到默认值{ networkPort, 4891, }, // 默认端口 4891 { serverChat, false }, // 默认不启用即 API Server 默认关闭serverChat对应配置文件GPT4All.ini的[General] serverChattrue可参考测试用例 test_server_api.py 中构造的配置。每个端点处理函数在执行前都会检查该开关未启用时统一返回401 Unauthorized// server.cpp 每个路由处理函数开头 if (!MySettings::globalInstance()-serverChat()) return QHttpServerResponse(QHttpServerResponder::StatusCode::Unauthorized);Server::start()中的监听逻辑也解释了为什么只能从本机访问server.cppauto port MySettings::globalInstance()-networkPort(); if (!tcpServer-listen(QHostAddress::LocalHost, port)) { ... }三、连接 API ServerBase URL 与网络约束Base URL 为http://localhost:4891/v1如果改用了其他端口则替换为http://localhost:PORT_NUM/v1。服务仅接受 HTTP 连接不支持 HTTPS且仅监听 127.0.0.1——注意它不监听 IPv6 的本地回环地址::1。第二点约束正对应上面源码中QHostAddress::LocalHost的取值IPv4 回环地址 127.0.0.1。此外服务端对所有响应统一附加Access-Control-Allow-Origin: *头server.cpp因此从 localhost 上的 Web 页面发起跨域调用时不会被浏览器拦截但这也再次提醒该设计面向本机受信环境不要自行改绑公网地址。四、API 端点总览MethodPath说明GET/v1/models列出可用已安装模型GET/v1/models/name获取指定模型的详细信息POST/v1/completions生成文本补全text completionPOST/v1/chat/completions生成对话补全chat completion四个路由均在Server::start()中注册server.cpp。当使用错误的 HTTP 方法访问这些路径时服务器会返回405 Method Not Allowed并附带提示性的错误信息例如对/v1/models发 POST 会得到{error: {message: Not allowed to POST on /v1/models. (HINT: Perhaps you meant to use a different HTTP method?), type: invalid_request_error, param: null, code: null}}访问不存在的路径如/v1/foobarbaz则返回404。这些行为都可以由仓库中的集成测试 test_server_api.py 逐条验证。请求参数支持哪些拒绝哪些BaseCompletionRequestserver.cpp对请求体做了严格的参数解析JSON 会先无损转换为 CBOR 以保留类型信息随后逐项校验类型与取值范围任何未识别的参数都会直接抛出invalid_request_errorHTTP 400。对使用者来说这是比静默忽略未知参数更严格的兼容策略支持的参数参数类型取值/默认说明modelstring必填模型名称与已安装模型名或模型文件名匹配messages非空对象数组必填chat每项含rolesystem/user/assistant与content不允许多余键promptstring必填completions补全提示词max_tokensint默认 16最小 1最大生成 token 数nint默认 1最小 1返回的 choice 数量temperaturenumber默认 1.0范围 0–2采样温度top_pnumber默认 1.0范围 0–1核采样min_pnumber默认 0.0范围 0–1最小概率过滤echobool仅 completions 有效为 true 时响应包含 prompt 原文userstring校验但不使用接受但忽略frequency_penalty/presence_penaltynumber只能为 0非 0 即报not supported明确不支持提供即返回 400的参数seed、stop、stream因此该服务目前不支持流式输出、stream_options、logprobs、logit_bias、suffix、best_of大于 n 时、response_format、tools、tool_choice、function_call、functions等见 server.cpp 与 ChatRequest::parseImpl。若你的客户端默认开启stream: true需要显式关闭。错误响应遵循 OpenAI 风格{error: {message: stream is not supported, type: invalid_request_error, param: null, code: null}}模型匹配规则handleCompletionRequest/handleChatRequest中的模型选择逻辑server.cpp是遍历已安装模型request.model与模型的name()或filename()任一匹配即选用若都不匹配则回退到应用当前的默认模型并非报错。模型加载时上下文会被重置与模型是否已加载无关。五、请求示例以下示例完整继承自官方文档。以Phi-3 Mini Instruct为例请替换为你实际安装的模型名可通过GET /v1/models查询cURLcurl -X POST http://localhost:4891/v1/chat/completions -d { model: Phi-3 Mini Instruct, messages: [{role:user,content:Who is Lionel Messi?}], max_tokens: 50, temperature: 0.28 }PowerShellInvoke-WebRequest -URI http://localhost:4891/v1/chat/completions -Method POST -ContentType application/json -Body { model: Phi-3 Mini Instruct, messages: [{role:user,content:Who is Lionel Messi?}], max_tokens: 50, temperature: 0.28 }GET 模型列表curl http://localhost:4891/v1/models响应结构/v1/chat/completions成功时返回标准chat.completion对象server.cpp{ id: placeholder, object: chat.completion, created: 1720000000, model: Phi-3 Mini Instruct, choices: [ { index: 0, message: {role: assistant, content: ...}, finish_reason: stop, logprobs: null } ], usage: {prompt_tokens: 23, completion_tokens: 50, total_tokens: 73} }其中finish_reason的判定逻辑是当累计responseTokens request.max_tokens时为length否则为stop。/v1/completions则返回object: text_completionchoices 中带text字段echo: true时text会拼接上 prompt 原文。usage中的 token 统计直接来自推理引擎返回的promptTokens/responseTokens。/v1/models返回 OpenAI 风格列表每个模型对象modelToJsonserver.cpp包含id、object: model、owned_by: humanity、root、permissions占位权限对象allow_view: true等字段——期望的完整结构可对照测试常量EXPECTED_MODEL_INFOtest_server_api.py。六、LocalDocs 集成从 API 中获取 RAG 参考官方文档给出的启用流程注意LocalDocs 目前只能通过 GPT4All UI 激活无法通过 API 本身开启在 GPT4All 应用中打开 Chats 视图滚动到聊天历史侧边栏底部选中server chat它的背景色与其他会话不同在右侧边栏中激活所需的 LocalDocs 集合。启用后所有发往本地 LLM 的 API 调用都会自动从 LocalDocs 集合中检索相关参考并把片段拼入输入消息供模型回答。LocalDocs 的工作原理基于 Nomic AI 的本地嵌入模型将文档切块并向量化、按语义相似度检索详见 LocalDocs 文档。如何取回参考来源检索到的参考位于 API 响应对象的response[choices][0][references]中。文档列出的字段为text从参考文档中抽取的实际文本内容author参考文档的作者如可用date参考文档的创建日期如可用page片段所在页码目前仅 PDF 文档支持title参考文档的标题如可用。从源码看实际序列化由resultToJsonserver.cpp完成它对应的数据结构是 database.h 中的ResultInfo因此 API 响应里还会额外包含file文件名、path完整路径、collection集合名、from/to文本起止行号非 PDF 文档时用于定位等字段比文档列举的更丰富。源码中有两个容易踩坑的细节references字段受开关控制只有当设置localDocsShowReferences为 truemysettings.cpp时choices 才会插入references键server.cpp若集合未检索到任何结果该字段为null而非空数组。集合状态通过server chat传递Server构造函数订阅了Chat::collectionListChanged信号server.h即你在 UI 中为 server 会话勾选的集合列表会同步到m_collections再随promptInternalChat(m_collections, ...)传入推理管线——这也解释了为什么必须在 Chats 视图中选中 server chat 并在那里激活集合。七、用仓库自带测试验证你的接入仓库提供了基于requests的端到端测试 test_server_api.py它通过临时配置目录写入GPT4All.ini[General] serverChattrue启动真实应用并访问http://localhost:4891/v1。几个值得复用的断言模式空模型列表GET /v1/models返回{object: list, data: []}不存在的模型GET /v1/models/foo返回空对象{}非法 JSON 请求体POST /v1/completions返回 400 且消息为error parsing request JSON: illegal value温度回归测试对应上游问题 #3202 的修复以temperature0.5的补全请求应当成功防止旧版本中该参数导致崩溃的问题复发。八、限制与注意事项仅 HTTP、仅 127.0.0.1无 HTTPS不接受 IPv6 回环地址本质上是本机受信接口不支持流式输出stream: true会直接 400长响应需等待完整结果部分参数不支持seed、stop、logprobs、tools等见上表依赖这些特性的客户端需要调整配置端口修改需重启应用设置项帮助文案明确说明LocalDocs 只能通过 UI 激活且references输出依赖localDocsShowReferences设置开启源码注释中也提到top_k、repeat_penalty等参数目前取自UI 的模型设置而非 API 请求因此相同请求在不同界面设置下可能产生不同结果server.cpp 的FIXME注释。设置项本身带有警告文案Expose an OpenAI-Compatible server to localhost. WARNING: Results in increased resource usage.即开启 API Server 会带来额外的常驻资源占用。以上所有端点行为、参数约束与响应结构均可在 server.cpp 与 test_server_api.py 中逐条对照便于你把 GPT4All 作为 OpenAI 兼容后端接入自研 Agent、脚本或现有工具链。【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4all创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GPT4All 本地 API Server 实战指南：用 OpenAI 兼容 HTTP 接口驱动本地 LLM 并接入 LocalDocs
GPT4All 本地 API Server 实战指南用 OpenAI 兼容 HTTP 接口驱动本地 LLM 并接入 LocalDocs【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4all本篇技术指南基于 GPT4All 官方文档 GPT4All API Server 展开系统讲解如何在 GPT4All Chat 桌面应用中启用内置的本地 HTTP API Server、使用 cURL/PowerShell 等工具发起 OpenAI 兼容请求并结合仓库源码server.cpp深入解析各端点的请求参数校验、响应结构与 LocalDocs 检索增强RAG集成的完整机制。读完本文你可以让任何支持 OpenAI API 的客户端直接调用自己硬件上运行的模型并从 API 响应中读取 LocalDocs 检索到的参考片段。一、核心特性与定位GPT4All 提供的本地 API Server 让你在自己的硬件上通过 HTTP API 运行大语言模型。官方文档概括了三个关键特性Local Execution本地执行模型完全运行在本地硬件上保障隐私与离线可用性LocalDocs Integration本地文档集成API 调用时可从 LocalDocs 集合中检索与问题语义相关的文本片段作为上下文注入给 LLMOpenAI API CompatibilityOpenAI API 兼容现有的 OpenAI 兼容客户端和工具无需改造即可指向本地模型。从源码结构看该服务由桌面应用内的Server类实现server.h它继承自ChatLLM基于 Qt6 的QHttpServerQTcpServer构建。这意味着 API Server 与桌面 UI 共享同一个模型加载、对话上下文与 LocalDocs 数据库管线——API 请求实际上会写入并出现在服务器聊天会话中。二、激活 API Server官方文档给出的启用步骤如下打开 GPT4All Chat 桌面应用进入SettingsApplication向下滚动到Advanced高级区域勾选Enable Local API Server选项服务器默认监听4891端口可通过API Server Port设置项改用其他端口。这一操作在源码中有明确对应ApplicationSettings.qml 中定义了Enable Local API Server复选框直接绑定到MySettings.serverChat属性旁边的API Server Port设置项帮助文案为 The port to use for the local server. Requires restart.说明修改端口需要重启应用才能生效。在 mysettings.cpp 中可以看到默认值{ networkPort, 4891, }, // 默认端口 4891 { serverChat, false }, // 默认不启用即 API Server 默认关闭serverChat对应配置文件GPT4All.ini的[General] serverChattrue可参考测试用例 test_server_api.py 中构造的配置。每个端点处理函数在执行前都会检查该开关未启用时统一返回401 Unauthorized// server.cpp 每个路由处理函数开头 if (!MySettings::globalInstance()-serverChat()) return QHttpServerResponse(QHttpServerResponder::StatusCode::Unauthorized);Server::start()中的监听逻辑也解释了为什么只能从本机访问server.cppauto port MySettings::globalInstance()-networkPort(); if (!tcpServer-listen(QHostAddress::LocalHost, port)) { ... }三、连接 API ServerBase URL 与网络约束Base URL 为http://localhost:4891/v1如果改用了其他端口则替换为http://localhost:PORT_NUM/v1。服务仅接受 HTTP 连接不支持 HTTPS且仅监听 127.0.0.1——注意它不监听 IPv6 的本地回环地址::1。第二点约束正对应上面源码中QHostAddress::LocalHost的取值IPv4 回环地址 127.0.0.1。此外服务端对所有响应统一附加Access-Control-Allow-Origin: *头server.cpp因此从 localhost 上的 Web 页面发起跨域调用时不会被浏览器拦截但这也再次提醒该设计面向本机受信环境不要自行改绑公网地址。四、API 端点总览MethodPath说明GET/v1/models列出可用已安装模型GET/v1/models/name获取指定模型的详细信息POST/v1/completions生成文本补全text completionPOST/v1/chat/completions生成对话补全chat completion四个路由均在Server::start()中注册server.cpp。当使用错误的 HTTP 方法访问这些路径时服务器会返回405 Method Not Allowed并附带提示性的错误信息例如对/v1/models发 POST 会得到{error: {message: Not allowed to POST on /v1/models. (HINT: Perhaps you meant to use a different HTTP method?), type: invalid_request_error, param: null, code: null}}访问不存在的路径如/v1/foobarbaz则返回404。这些行为都可以由仓库中的集成测试 test_server_api.py 逐条验证。请求参数支持哪些拒绝哪些BaseCompletionRequestserver.cpp对请求体做了严格的参数解析JSON 会先无损转换为 CBOR 以保留类型信息随后逐项校验类型与取值范围任何未识别的参数都会直接抛出invalid_request_errorHTTP 400。对使用者来说这是比静默忽略未知参数更严格的兼容策略支持的参数参数类型取值/默认说明modelstring必填模型名称与已安装模型名或模型文件名匹配messages非空对象数组必填chat每项含rolesystem/user/assistant与content不允许多余键promptstring必填completions补全提示词max_tokensint默认 16最小 1最大生成 token 数nint默认 1最小 1返回的 choice 数量temperaturenumber默认 1.0范围 0–2采样温度top_pnumber默认 1.0范围 0–1核采样min_pnumber默认 0.0范围 0–1最小概率过滤echobool仅 completions 有效为 true 时响应包含 prompt 原文userstring校验但不使用接受但忽略frequency_penalty/presence_penaltynumber只能为 0非 0 即报not supported明确不支持提供即返回 400的参数seed、stop、stream因此该服务目前不支持流式输出、stream_options、logprobs、logit_bias、suffix、best_of大于 n 时、response_format、tools、tool_choice、function_call、functions等见 server.cpp 与 ChatRequest::parseImpl。若你的客户端默认开启stream: true需要显式关闭。错误响应遵循 OpenAI 风格{error: {message: stream is not supported, type: invalid_request_error, param: null, code: null}}模型匹配规则handleCompletionRequest/handleChatRequest中的模型选择逻辑server.cpp是遍历已安装模型request.model与模型的name()或filename()任一匹配即选用若都不匹配则回退到应用当前的默认模型并非报错。模型加载时上下文会被重置与模型是否已加载无关。五、请求示例以下示例完整继承自官方文档。以Phi-3 Mini Instruct为例请替换为你实际安装的模型名可通过GET /v1/models查询cURLcurl -X POST http://localhost:4891/v1/chat/completions -d { model: Phi-3 Mini Instruct, messages: [{role:user,content:Who is Lionel Messi?}], max_tokens: 50, temperature: 0.28 }PowerShellInvoke-WebRequest -URI http://localhost:4891/v1/chat/completions -Method POST -ContentType application/json -Body { model: Phi-3 Mini Instruct, messages: [{role:user,content:Who is Lionel Messi?}], max_tokens: 50, temperature: 0.28 }GET 模型列表curl http://localhost:4891/v1/models响应结构/v1/chat/completions成功时返回标准chat.completion对象server.cpp{ id: placeholder, object: chat.completion, created: 1720000000, model: Phi-3 Mini Instruct, choices: [ { index: 0, message: {role: assistant, content: ...}, finish_reason: stop, logprobs: null } ], usage: {prompt_tokens: 23, completion_tokens: 50, total_tokens: 73} }其中finish_reason的判定逻辑是当累计responseTokens request.max_tokens时为length否则为stop。/v1/completions则返回object: text_completionchoices 中带text字段echo: true时text会拼接上 prompt 原文。usage中的 token 统计直接来自推理引擎返回的promptTokens/responseTokens。/v1/models返回 OpenAI 风格列表每个模型对象modelToJsonserver.cpp包含id、object: model、owned_by: humanity、root、permissions占位权限对象allow_view: true等字段——期望的完整结构可对照测试常量EXPECTED_MODEL_INFOtest_server_api.py。六、LocalDocs 集成从 API 中获取 RAG 参考官方文档给出的启用流程注意LocalDocs 目前只能通过 GPT4All UI 激活无法通过 API 本身开启在 GPT4All 应用中打开 Chats 视图滚动到聊天历史侧边栏底部选中server chat它的背景色与其他会话不同在右侧边栏中激活所需的 LocalDocs 集合。启用后所有发往本地 LLM 的 API 调用都会自动从 LocalDocs 集合中检索相关参考并把片段拼入输入消息供模型回答。LocalDocs 的工作原理基于 Nomic AI 的本地嵌入模型将文档切块并向量化、按语义相似度检索详见 LocalDocs 文档。如何取回参考来源检索到的参考位于 API 响应对象的response[choices][0][references]中。文档列出的字段为text从参考文档中抽取的实际文本内容author参考文档的作者如可用date参考文档的创建日期如可用page片段所在页码目前仅 PDF 文档支持title参考文档的标题如可用。从源码看实际序列化由resultToJsonserver.cpp完成它对应的数据结构是 database.h 中的ResultInfo因此 API 响应里还会额外包含file文件名、path完整路径、collection集合名、from/to文本起止行号非 PDF 文档时用于定位等字段比文档列举的更丰富。源码中有两个容易踩坑的细节references字段受开关控制只有当设置localDocsShowReferences为 truemysettings.cpp时choices 才会插入references键server.cpp若集合未检索到任何结果该字段为null而非空数组。集合状态通过server chat传递Server构造函数订阅了Chat::collectionListChanged信号server.h即你在 UI 中为 server 会话勾选的集合列表会同步到m_collections再随promptInternalChat(m_collections, ...)传入推理管线——这也解释了为什么必须在 Chats 视图中选中 server chat 并在那里激活集合。七、用仓库自带测试验证你的接入仓库提供了基于requests的端到端测试 test_server_api.py它通过临时配置目录写入GPT4All.ini[General] serverChattrue启动真实应用并访问http://localhost:4891/v1。几个值得复用的断言模式空模型列表GET /v1/models返回{object: list, data: []}不存在的模型GET /v1/models/foo返回空对象{}非法 JSON 请求体POST /v1/completions返回 400 且消息为error parsing request JSON: illegal value温度回归测试对应上游问题 #3202 的修复以temperature0.5的补全请求应当成功防止旧版本中该参数导致崩溃的问题复发。八、限制与注意事项仅 HTTP、仅 127.0.0.1无 HTTPS不接受 IPv6 回环地址本质上是本机受信接口不支持流式输出stream: true会直接 400长响应需等待完整结果部分参数不支持seed、stop、logprobs、tools等见上表依赖这些特性的客户端需要调整配置端口修改需重启应用设置项帮助文案明确说明LocalDocs 只能通过 UI 激活且references输出依赖localDocsShowReferences设置开启源码注释中也提到top_k、repeat_penalty等参数目前取自UI 的模型设置而非 API 请求因此相同请求在不同界面设置下可能产生不同结果server.cpp 的FIXME注释。设置项本身带有警告文案Expose an OpenAI-Compatible server to localhost. WARNING: Results in increased resource usage.即开启 API Server 会带来额外的常驻资源占用。以上所有端点行为、参数约束与响应结构均可在 server.cpp 与 test_server_api.py 中逐条对照便于你把 GPT4All 作为 OpenAI 兼容后端接入自研 Agent、脚本或现有工具链。【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4all创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考