PentAGI 接入 Ollama 本地模型：从环境变量配置到源码级实现解析-创锋一号

PentAGI 接入 Ollama 本地模型：从环境变量配置到源码级实现解析

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi

PentAGI 是支持全自主渗透测试任务的 AI Agent 系统，而 Ollama Provider 是其接入本地大模型的官方通道——通过它，你可以让 PentAGI 全部 Agent 角色（规划、编码、渗透、搜索等）跑在本机或内网自建的模型服务上，无需任何 API Key 与联网计费。读完本文，你将掌握 Ollama 的安装接入、环境变量与 YAML 自定义配置、模型自动拉取/发现机制的调优方法，并透过 ollama.go 的源码理解这些开关背后真实的调用链。

一、Ollama Provider 是什么

Ollama Provider 使 PentAGI 能够通过 Ollama 中，Ollama 被注册为一种独立的 Provider 类型（ProviderOllama = "ollama"），与 OpenAI、Anthropic、Gemini、Bedrock 等云端厂商并列，属于"自托管/本地"阵营。其核心价值在于：

本地推理：模型权重保存在你自己的服务器上，数据不出内网；
零定价：不产生按 token 计费的成本，没有 API 限额；
动态模型发现：可自动探测服务器上已安装的模型并纳入可选列表。

在 registry.go 中，Ollama Provider 的启用条件是OLLAMA_SERVER_URL环境变量非空，也就是说：只要设置了服务器地址，PentAGI 就会把它作为一个可用 Provider 注册进系统。

二、安装与启动 Ollama 服务器

按照官方安装指南在你的系统上安装 Ollama 服务器；
启动 Ollama 服务，默认监听在http://localhost:11434；
拉取所需模型，例如：ollama pull gemma3:1b。

安装完成后可用ollama list查看本机已有哪些模型，用ollama pull <model-name>下载新模型。PentAGI 侧并不要求提前下载全部模型——如果启用了自动拉取功能（见下文），它会在启动时替你补齐。

三、环境变量配置

Ollama 相关配置项统一定义在 config.go，全部通过环境变量注入。

必选变量

# Ollama 服务器地址（默认：http://localhost:11434） OLLAMA_SERVER_URL=http://localhost:11434

这是唯一必须设置的变量，也是 Provider 注册的开关。源码中newOllamaClient会对其执行url.Parse解析，因此地址格式必须合法（例如http://localhost:11434）。

可选变量

# 推理默认模型（可选，默认：llama3.1:8b-instruct-q8_0） OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0 # 自定义配置文件路径（可选，YAML/JSON 均可） OLLAMA_SERVER_CONFIG_PATH=/path/to/ollama_config.yml # 模型管理设置（可选） OLLAMA_SERVER_PULL_MODELS_TIMEOUT=600 # 模型下载超时（秒），默认 600 OLLAMA_SERVER_PULL_MODELS_ENABLED=false # 启动时自动下载模型，默认 false OLLAMA_SERVER_LOAD_MODELS_ENABLED=false # 启动时从服务器加载模型列表，默认 false # 需要代理时设置 PROXY_URL=http://proxy:8080 # Ollama Cloud 订阅场景下的 API Key（可选） OLLAMA_SERVER_API_KEY=ollama-xxx

几点说明：

OLLAMA_SERVER_MODEL在源码中作为baseModel，不仅用于默认推理，还参与自动拉取的模型清单构建（getConfigModelsList会把它作为清单第一项）。
OLLAMA_SERVER_PULL_MODELS_TIMEOUT的类型是 int、单位为秒；New()中若该值<= 0会回退到内置默认值defaultPullTimeout = 10 * time.Minute（见 ollama.go）。
OLLAMA_SERVER_API_KEY是给 Ollama Cloud 用的：源码中只要该变量非空，就会通过ollama.WithAPIKey(...)注入认证信息（见 ollama.go），让 PentAGI 既能连本地免费实例，也能连 Ollama 的云端订阅服务。
PROXY_URL会经由system.GetHTTPClient(cfg)构造带代理的 HTTP 客户端，同时用于拉模型 API 与推理调用（对应测试用例 TestOllamaProviderWithProxy）。

四、高级配置：模型管理开关

PentAGI 通过三个开关控制与 Ollama 服务器的交互方式：

自动拉取模型（OLLAMA_SERVER_PULL_MODELS_ENABLED=true）：启动时自动下载配置文件中指定的模型。源码路径为New()中ensureModelsAvailable(ctx, apiClient, configModels)——它会并发地对模型清单逐个检查：先用client.Show()探测模型是否已存在于本地（快速路径，存在则跳过下载），不存在才发起client.Pull()拉取（见 ollama.go）。
拉取超时（OLLAMA_SERVER_PULL_MODELS_TIMEOUT）：等待模型下载的最长时间，默认 600 秒。
加载模型列表（OLLAMA_SERVER_LOAD_MODELS_ENABLED=true）：通过 API 向 Ollama 服务器查询可用模型。源码中对应loadAvailableModelsFromServer()，调用client.List(ctx)并逐条转换为pconfig.ModelConfig（注意其Price字段被显式置为 nil，见 ollama.go，这正是"本地推理无计费"在数据模型层面的体现）。

性能提示：启用OLLAMA_SERVER_LOAD_MODELS_ENABLED会在启动时增加延迟，因为 PentAGI 需要查询 Ollama API。每次 API 查询本身受defaultAPICallTimeout = 10 * time.Second约束；如果你只使用配置文件里指定的模型，建议关闭它以获得最快启动。

五、支持的模型

Provider 会动态加载你本地 Ollama 服务器上的模型，可用模型完全取决于你本机安装了什么。常见模型家族包括：

Gemma 系列：gemma3:1b、gemma3:2b、gemma3:7b、gemma3:27b
Llama 系列：llama3.1:7b、llama3.1:8b、llama3.1:8b-instruct-q8_0、llama3.1:8b-instruct-fp16、llama3.1:70b、llama3.2:1b、llama3.2:3b、llama3.2:90b
Qwen 系列：qwen2.5:1.5b、qwen2.5:3b、qwen2.5:7b、qwen2.5:14b、qwen2.5:32b、qwen2.5:72b
DeepSeek 系列：deepseek-r1:1.5b、deepseek-r1:7b、deepseek-r1:8b、deepseek-r1:14b、deepseek-r1:32b
Embedding 模型：nomic-embed-text

在服务器上查看可用模型：ollama list；下载新模型：ollama pull <model-name>。

从源码看，"动态发现"链路是：OLLAMA_SERVER_LOAD_MODELS_ENABLED=true→loadAvailableModelsFromServer()→client.List()→pconfig.ModelsConfig→ 通过GetModels()暴露给上层，供模型选择界面使用；未启用时，可用模型列表只包含OLLAMA_SERVER_MODEL指定的基础模型（见 ollama.go）。

六、功能特性一览

动态模型发现：启用后自动检测 Ollama 服务器上已安装的模型；
模型缓存：关闭加载时只使用已配置的模型，不产生额外 API 调用；
本地推理：无需 API Key，模型完全在本地运行；
自动模型拉取：启用后按需自动下载模型；
Agent 专业化：为不同 Agent 类型（assistant、coder、pentester 等）提供差异化参数配置；
工具调用支持：兼容支持 function calling 的模型（CallWithTools通过llms.WithTools注入工具定义，见 ollama.go）；
流式输出：实时响应流（CallEx/CallWithTools均通过llms.WithStreamingFunc挂接流回调）；
自定义配置：用 YAML 配置文件覆盖默认参数；
零计费：本地模型无使用成本。

另外值得注意的一个实现细节：ModelWithPrefix()对 Ollama 直接透传模型名而不加前缀（见 ollama.go），这与 LiteLLM 网关类 Provider 的行为不同，说明 PentAGI 将 Ollama 视为"直连原生后端"。同时，在 provider.go 的推理能力映射中，Ollama 被标记为reasoning.ProviderUnknown——即不为其假设任何厂商特有的推理开关协议。

七、Agent 类型与默认参数

Provider 支持 PentAGI 的全部 Agent 类型，并可为每种类型提供差异化配置。文档中给出的定位参考如下：

simple：通用对话
assistant：AI 助手类任务
coder：代码生成
pentester：安全测试（渗透主角色）
generator：内容生成（如攻击计划初稿）
refiner：内容精炼
searcher：信息检索
以及simple_json、primary_agent、adviser、reflector、enricher、installer等更多类型

这些 Agent 类型与pconfig.ProviderOptionsType常量一一对应（见 config.go），总计 13 种。注意：仓库内置的 config.yml 中，各 Agent 的实际默认值为temperature: 1.0、top_p: 0.9~0.95、n: 1，max_tokens从 4096（simple_json/reflector/enricher）到 20480（generator/coder）不等；文档中列举的 0.1~0.4 温度与 3000/6000/8000 上限属于参考性建议值，实际生效值以内置配置或你自定义的配置为准。若未对某类型单独配置，GetOptionsForType会回退到BuildProviderConfig中构造的默认选项（n=1、max_tokens=32768、model=OLLAMA_SERVER_MODEL，见 ollama.go）。

八、自定义配置（YAML 覆盖默认参数）

当内置默认参数不满足需求时，可以创建自定义配置文件覆盖任意 Agent 的参数：

simple: model: "llama3.1:8b-instruct-q8_0" temperature: 0.2 top_p: 0.3 n: 1 max_tokens: 4000 coder: model: "deepseek-r1:8b" temperature: 0.1 top_p: 0.2 n: 1 max_tokens: 8000

然后通过OLLAMA_SERVER_CONFIG_PATH指向该文件即可。

源码侧的加载逻辑（DefaultProviderConfig）为：若OLLAMA_SERVER_CONFIG_PATH为空，则读取go:embed进二进制的内置 config.yml；否则读取外部文件，读不到时回退内置配置（见 ollama.go，对应测试 TestOllamaProviderWithCustomConfig）。

配置解析由pconfig.LoadConfigData完成，同时支持 YAML 与 JSON 两种格式，并兼容旧版agent:字段（自动映射为primary_agent）。AgentConfig支持的可调字段（见 config.go）包括：model、max_tokens、temperature、top_k、top_p、min_p、n、min_length、max_length、repetition_penalty、frequency_penalty、presence_penalty、json、response_mime_type、reasoning、extra_body、price。其中值得注意的约束（Validate()）：

temperature范围 [0, 2]，top_p范围 [0, 1]；
repetition_penalty范围 [0, 2]，frequency_penalty/presence_penalty范围 [-2, 2]；
reasoning.max_tokens上限 32768；
配置了json: true会追加llms.WithJSONMode()，要求模型输出 JSON。

仓库还提供了一份完整的Ollama Cloud订阅配置样例 ollama-cloud.provider.yml，展示了为 13 个 Agent 角色逐一挑选模型（如 pentester 用deepseek-v4-pro、coder 用kimi-k2.7-code）的做法，并解释了为何刻意排除 Google/OpenAI 系模型（安全对齐导致的误拒问题）——对自建模型选型有直接参考价值。该文件还明确指出：对原生 Ollama Provider，reasoning:字段是无效配置（langchaingo 的 llms/ollama 客户端不读取 reasoning 参数，仅被动解析响应文本中的<thinking>标签），因此文件整体省略了该字段。

九、定价

Ollama 提供免费的本地推理——无使用成本、无 API 限额。这一点在数据层有明确体现：loadAvailableModelsFromServer将模型Price置为 nil，GetPriceInfo对 Ollama 返回空价格信息（对应测试 TestOllamaProviderPricing），因此 PentAGI 的计费统计对 Ollama 场景显示为零成本。

十、示例：启动 PentAGI 使用 Ollama

# 设置环境变量 export OLLAMA_SERVER_URL=http://localhost:11434 # 启动 PentAGI（Ollama Provider 自动注册） ./pentagi

更完整的实战组合（本地推理 + 自动补齐模型）：

export OLLAMA_SERVER_URL=http://localhost:11434 export OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0 export OLLAMA_SERVER_PULL_MODELS_ENABLED=true export OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900 export OLLAMA_SERVER_LOAD_MODELS_ENABLED=true ./pentagi

启动过程可用 ollama_test.go 中的TestNew作为行为参照：默认配置必须成功构建出全部 Agent 类型的参数选项、Provider 类型必须为ollama、Model()必须能返回非空模型名，且GetUsage能从PromptTokens/CompletionTokens字段正确统计输入输出 token（config.go）。

十一、故障排查

连接错误：确保 Ollama 服务器已启动且地址可达（默认http://localhost:11434）。注意New()会先创建 API 客户端再创建 LLM 客户端，任何一步失败都会导致 Provider 初始化失败。
模型未找到：先执行ollama pull <model-name>拉取模型；或启用OLLAMA_SERVER_PULL_MODELS_ENABLED=true让 PentAGI 自动补齐。注意自动拉取使用client.Show()快速路径判断模型是否已存在，探测本身也有 10 秒超时约束。
性能问题：使用更小的模型以获得更快的推理速度，或升级硬件。
内存问题：运行大模型时密切监控系统内存占用。

十二、小结

Ollama Provider 是 PentAGI 中部署成本最低、接入最简单的推理通道：一个OLLAMA_SERVER_URL即可完成注册，配合OLLAMA_SERVER_PULL_MODELS_ENABLED与OLLAMA_SERVER_LOAD_MODELS_ENABLED两个开关即可在"快速静态配置"与"动态自动发现"两种模式间切换，再通过OLLAMA_SERVER_CONFIG_PATH指向 YAML 文件即可对 13 种 Agent 角色做精细化参数调优。无论你是想在渗透测试流程里跑通端到端实验，还是为内网环境构建完全离线的 Agent 系统，本文涉及的配置项与源码调用链都能帮你快速定位到正确的组合方式。

企业官网建设流程全解析