wehub-resource-sync
3739 lines
186 KiB
Markdown
3739 lines
186 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/vxcontrol/pentagi) · [上游 README](https://github.com/vxcontrol/pentagi/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# PentAGI
|
||
|
||
<div align="center" style="font-size: 1.5em; margin: 20px 0;">
|
||
<strong>P</strong>enetration testing <strong>A</strong>rtificial <strong>G</strong>eneral <strong>I</strong>ntelligence
|
||
</div>
|
||
<br>
|
||
<div align="center">
|
||
|
||
> **加入社区！** 与安全研究人员、AI 爱好者以及道德黑客（ethical hackers）同行交流。获取支持、分享见解，并及时了解 PentAGI 的最新进展。
|
||
|
||
[](https://discord.gg/2xrMh7qX6m)⠀[](https://t.me/+Ka9i6CNwe71hMWQy)
|
||
|
||
<a href="https://trendshift.io/repositories/15161" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15161" alt="vxcontrol%2Fpentagi | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
||
|
||
</div>
|
||
|
||
## 目录
|
||
|
||
- [概述](#overview)
|
||
- [功能特性](#features)
|
||
- [架构](#architecture)
|
||
- [高级智能体监督](#advanced-agent-supervision)
|
||
- [快速开始](#quick-start)
|
||
- [登录后如何使用 PentAGI](#how-to-use-pentagi-after-login)
|
||
- [API 访问](#api-access)
|
||
- [LLM 提供商配置](#custom-llm-provider-configuration)
|
||
- [Ollama](#ollama-provider-configuration)
|
||
- [OpenAI](#openai-provider-configuration)
|
||
- [Anthropic](#anthropic-provider-configuration)
|
||
- [Google AI (Gemini)](#google-ai-gemini-provider-configuration)
|
||
- [AWS Bedrock](#aws-bedrock-provider-configuration)
|
||
- [DeepSeek](#deepseek-provider-configuration)
|
||
- [GLM](#glm-provider-configuration)
|
||
- [Kimi](#kimi-provider-configuration)
|
||
- [Qwen](#qwen-provider-configuration)
|
||
- [高级配置](#advanced-setup)
|
||
- [Langfuse 集成](#langfuse-integration)
|
||
- [监控与可观测性](#monitoring-and-observability)
|
||
- [知识图谱 (Graphiti)](#knowledge-graph-integration-graphiti)
|
||
- [OAuth 集成](#github-and-google-oauth-integration)
|
||
- [Docker 镜像配置](#docker-image-configuration)
|
||
- [开发](#development)
|
||
- [测试 LLM 智能体](#testing-llm-agents)
|
||
- [Embedding 配置与测试](#embedding-configuration-and-testing)
|
||
- [使用 ftester 进行函数测试](#function-testing-with-ftester)
|
||
- [构建](#building)
|
||
- [致谢](#credits)
|
||
- [许可证](#license)
|
||
|
||
## 概述
|
||
|
||
PentAGI 是一款创新的自动化安全测试工具，采用前沿的人工智能技术。该项目面向信息安全专业人员、研究人员和爱好者，为他们提供强大且灵活的渗透测试解决方案。
|
||
|
||
你可以观看视频 **PentAGI overview**：
|
||
[](https://youtu.be/R70x5Ddzs1o)
|
||
|
||
## 功能特性
|
||
|
||
- 安全且隔离。所有操作均在沙箱化的 Docker 环境中执行，实现完全隔离。
|
||
- 完全自主。由 AI 驱动的智能体自动确定并执行渗透测试步骤，可选执行监控与智能任务规划，以提升可靠性。
|
||
- 专业渗透测试工具。内置 20+ 款专业安全工具，包括 nmap、metasploit、sqlmap 等。
|
||
- 智能记忆系统。长期存储研究成果与成功方法，供后续使用。
|
||
- 知识图谱集成。基于 Graphiti 的知识图谱，使用 Neo4j 进行语义关系追踪与高级上下文理解。
|
||
- 网络情报。通过内置浏览器与 [scraper](https://hub.docker.com/r/vxcontrol/scraper) 从网络来源收集最新信息。
|
||
- 外部搜索系统。集成多种高级搜索 API，包括 [Tavily](https://tavily.com), [Traversaal](https://traversaal.ai), [Perplexity](https://www.perplexity.ai), [DuckDuckGo](https://duckduckgo.com/), [Google Custom Search](https://programmablesearchengine.google.com/), [Sploitus Search](https://sploitus.com) 以及 [Searxng](https://searxng.org)，用于全面的信息收集。
|
||
- 专家团队。委派系统配备专业化 AI 智能体，分别负责研究、开发与基础设施任务，并可选执行监控与智能任务规划，以便在较小模型上也能获得最佳性能。
|
||
- 全面监控。详细日志记录，并集成 Grafana/Prometheus，实现实时系统观测。
|
||
- 详细报告。生成详尽的漏洞报告及利用指南。
|
||
- 智能容器管理。根据具体任务需求自动选择 Docker 镜像。
|
||
- 现代界面。简洁直观的 Web UI，用于系统管理与监控。
|
||
- 完整 API。功能齐全的 REST 与 GraphQL API，支持 Bearer token 认证，便于自动化与集成。
|
||
- 持久化存储。所有命令与输出均存储在 PostgreSQL 中，并使用 [pgvector](https://hub.docker.com/r/vxcontrol/pgvector) 扩展。
|
||
- 可扩展架构。基于微服务的设计，支持水平扩展。
|
||
- 自托管方案。完全掌控部署与数据。
|
||
- 灵活认证。支持 10+ 种 LLM 提供商（[OpenAI](https://platform.openai.com/), [Anthropic](https://www.anthropic.com/), [Google AI/Gemini](https://ai.google.dev/), [AWS Bedrock](https://aws.amazon.com/bedrock/), [Ollama](https://ollama.com/), [DeepSeek](https://www.deepseek.com/en/), [GLM](https://z.ai/), [Kimi](https://platform.moonshot.ai/), [Qwen](https://www.alibabacloud.com/en/), Custom），以及聚合器（[OpenRouter](https://openrouter.ai/), [DeepInfra](https://deepinfra.com/)).。若要在生产环境本地部署，请参阅我们的 [vLLM + Qwen3.5-27B-FP8 指南](examples/guides/vllm-qwen35-27b-fp8.md)。
|
||
- API Token 认证。安全的 Bearer token 系统，用于以编程方式访问 REST 与 GraphQL API。
|
||
- 快速部署。通过 [Docker Compose](https://docs.docker.com/compose/) 轻松完成设置，并提供全面的环境配置。
|
||
|
||
### 当前能力边界
|
||
|
||
- PentAGI 目前是一个自主且由助手引导的渗透测试平台，而非 CALDERA 风格的入侵与攻击模拟（Breach and Attack Simulation，BAS）或带有预定义战役/攻击计划的对手仿真（adversary emulation）产品。
|
||
- 类似 BAS 的由智能体编写的攻击脚本应视为概念性工作或未来规划，而非当前已实现的功能。
|
||
- 当前的流程报告 UI 支持 Web 查看、复制到剪贴板、Markdown 下载与 PDF 下载。JSON 格式的 flow-report 导出目前未记录为受支持的输出格式。
|
||
- 提供商灵活性目前可通过内置提供商以及自定义/OpenAI 兼容端点实现。请参阅 [自定义 LLM 提供商配置](#custom-llm-provider-configuration) 与 [vLLM + Qwen3.5-27B-FP8 指南](examples/guides/vllm-qwen35-27b-fp8.md)。
|
||
|
||
## 架构
|
||
|
||
### 系统上下文
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
classDef person fill:#08427B,stroke:#073B6F,color:#fff
|
||
classDef system fill:#1168BD,stroke:#0B4884,color:#fff
|
||
classDef external fill:#666666,stroke:#0B4884,color:#fff
|
||
|
||
pentester["👤 Security Engineer
|
||
(User of the system)"]
|
||
|
||
pentagi["✨ PentAGI
|
||
(Autonomous penetration testing system)"]
|
||
|
||
target["🎯 target-system
|
||
(System under test)"]
|
||
llm["🧠 llm-provider
|
||
(OpenAI/Anthropic/Ollama/Bedrock/Gemini/Custom)"]
|
||
search["🔍 search-systems
|
||
(Google/DuckDuckGo/Tavily/Traversaal/Perplexity/Sploitus/Searxng)"]
|
||
langfuse["📊 langfuse-ui
|
||
(LLM Observability Dashboard)"]
|
||
grafana["📈 grafana
|
||
(System Monitoring Dashboard)"]
|
||
|
||
pentester --> |Uses HTTPS| pentagi
|
||
pentester --> |Monitors AI HTTPS| langfuse
|
||
pentester --> |Monitors System HTTPS| grafana
|
||
pentagi --> |Tests Various protocols| target
|
||
pentagi --> |Queries HTTPS| llm
|
||
pentagi --> |Searches HTTPS| search
|
||
pentagi --> |Reports HTTPS| langfuse
|
||
pentagi --> |Reports HTTPS| grafana
|
||
|
||
class pentester person
|
||
class pentagi system
|
||
class target,llm,search,langfuse,grafana external
|
||
|
||
linkStyle default stroke:#ffffff,color:#ffffff
|
||
```
|
||
|
||
<details>
|
||
<summary><b>容器架构</b>（点击展开）</summary>
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Core Services
|
||
UI[Frontend UI<br/>React + TypeScript]
|
||
API[Backend API<br/>Go + GraphQL]
|
||
DB[(Vector Store<br/>PostgreSQL + pgvector)]
|
||
MQ[Task Queue<br/>Async Processing]
|
||
Agent[AI Agents<br/>Multi-Agent System]
|
||
end
|
||
|
||
subgraph Knowledge Graph
|
||
Graphiti[Graphiti<br/>Knowledge Graph API]
|
||
Neo4j[(Neo4j<br/>Graph Database)]
|
||
end
|
||
|
||
subgraph Monitoring
|
||
Grafana[Grafana<br/>Dashboards]
|
||
VictoriaMetrics[VictoriaMetrics<br/>Time-series DB]
|
||
Jaeger[Jaeger<br/>Distributed Tracing]
|
||
Loki[Loki<br/>Log Aggregation]
|
||
OTEL[OpenTelemetry<br/>Data Collection]
|
||
end
|
||
|
||
subgraph Analytics
|
||
Langfuse[Langfuse<br/>LLM Analytics]
|
||
ClickHouse[ClickHouse<br/>Analytics DB]
|
||
Redis[Redis<br/>Cache + Rate Limiter]
|
||
MinIO[MinIO<br/>S3 Storage]
|
||
end
|
||
|
||
subgraph Security Tools
|
||
Scraper[Web Scraper<br/>Isolated Browser]
|
||
PenTest[Security Tools<br/>20+ Pro Tools<br/>Sandboxed Execution]
|
||
end
|
||
|
||
UI --> |HTTP/WS| API
|
||
API --> |SQL| DB
|
||
API --> |Events| MQ
|
||
MQ --> |Tasks| Agent
|
||
Agent --> |Commands| PenTest
|
||
Agent --> |Queries| DB
|
||
Agent --> |Knowledge| Graphiti
|
||
Graphiti --> |Graph| Neo4j
|
||
|
||
API --> |Telemetry| OTEL
|
||
OTEL --> |Metrics| VictoriaMetrics
|
||
OTEL --> |Traces| Jaeger
|
||
OTEL --> |Logs| Loki
|
||
|
||
Grafana --> |Query| VictoriaMetrics
|
||
Grafana --> |Query| Jaeger
|
||
Grafana --> |Query| Loki
|
||
|
||
API --> |Analytics| Langfuse
|
||
Langfuse --> |Store| ClickHouse
|
||
Langfuse --> |Cache| Redis
|
||
Langfuse --> |Files| MinIO
|
||
|
||
classDef core fill:#f9f,stroke:#333,stroke-width:2px,color:#000
|
||
classDef knowledge fill:#ffa,stroke:#333,stroke-width:2px,color:#000
|
||
classDef monitoring fill:#bbf,stroke:#333,stroke-width:2px,color:#000
|
||
classDef analytics fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||
classDef tools fill:#fbb,stroke:#333,stroke-width:2px,color:#000
|
||
|
||
class UI,API,DB,MQ,Agent core
|
||
class Graphiti,Neo4j knowledge
|
||
class Grafana,VictoriaMetrics,Jaeger,Loki,OTEL monitoring
|
||
class Langfuse,ClickHouse,Redis,MinIO analytics
|
||
class Scraper,PenTest tools
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>实体关系</b>（点击展开）</summary>
|
||
|
||
```mermaid
|
||
erDiagram
|
||
Flow ||--o{ Task : contains
|
||
Task ||--o{ SubTask : contains
|
||
SubTask ||--o{ Action : contains
|
||
Action ||--o{ Artifact : produces
|
||
Action ||--o{ Memory : stores
|
||
|
||
Flow {
|
||
string id PK
|
||
string name "Flow name"
|
||
string description "Flow description"
|
||
string status "active/completed/failed"
|
||
json parameters "Flow parameters"
|
||
timestamp created_at
|
||
timestamp updated_at
|
||
}
|
||
|
||
Task {
|
||
string id PK
|
||
string flow_id FK
|
||
string name "Task name"
|
||
string description "Task description"
|
||
string status "pending/running/done/failed"
|
||
json result "Task results"
|
||
timestamp created_at
|
||
timestamp updated_at
|
||
}
|
||
|
||
SubTask {
|
||
string id PK
|
||
string task_id FK
|
||
string name "Subtask name"
|
||
string description "Subtask description"
|
||
string status "queued/running/completed/failed"
|
||
string agent_type "researcher/developer/executor"
|
||
json context "Agent context"
|
||
timestamp created_at
|
||
timestamp updated_at
|
||
}
|
||
|
||
Action {
|
||
string id PK
|
||
string subtask_id FK
|
||
string type "command/search/analyze/etc"
|
||
string status "success/failure"
|
||
json parameters "Action parameters"
|
||
json result "Action results"
|
||
timestamp created_at
|
||
}
|
||
|
||
Artifact {
|
||
string id PK
|
||
string action_id FK
|
||
string type "file/report/log"
|
||
string path "Storage path"
|
||
json metadata "Additional info"
|
||
timestamp created_at
|
||
}
|
||
|
||
Memory {
|
||
string id PK
|
||
string action_id FK
|
||
string type "observation/conclusion"
|
||
vector embedding "Vector representation"
|
||
text content "Memory content"
|
||
timestamp created_at
|
||
}
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Agent 交互</b>（点击展开）</summary>
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant O as Orchestrator
|
||
participant R as Researcher
|
||
participant D as Developer
|
||
participant E as Executor
|
||
participant VS as Vector Store
|
||
participant KB as Knowledge Base
|
||
|
||
Note over O,KB: Flow Initialization
|
||
O->>VS: Query similar tasks
|
||
VS-->>O: Return experiences
|
||
O->>KB: Load relevant knowledge
|
||
KB-->>O: Return context
|
||
|
||
Note over O,R: Research Phase
|
||
O->>R: Analyze target
|
||
R->>VS: Search similar cases
|
||
VS-->>R: Return patterns
|
||
R->>KB: Query vulnerabilities
|
||
KB-->>R: Return known issues
|
||
R->>VS: Store findings
|
||
R-->>O: Research results
|
||
|
||
Note over O,D: Planning Phase
|
||
O->>D: Plan attack
|
||
D->>VS: Query exploits
|
||
VS-->>D: Return techniques
|
||
D->>KB: Load tools info
|
||
KB-->>D: Return capabilities
|
||
D-->>O: Attack plan
|
||
|
||
Note over O,E: Execution Phase
|
||
O->>E: Execute plan
|
||
E->>KB: Load tool guides
|
||
KB-->>E: Return procedures
|
||
E->>VS: Store results
|
||
E-->>O: Execution status
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>记忆系统</b>（点击展开）</summary>
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "Long-term Memory"
|
||
VS[(Vector Store<br/>Embeddings DB)]
|
||
KB[Knowledge Base<br/>Domain Expertise]
|
||
Tools[Tools Knowledge<br/>Usage Patterns]
|
||
end
|
||
|
||
subgraph "Working Memory"
|
||
Context[Current Context<br/>Task State]
|
||
Goals[Active Goals<br/>Objectives]
|
||
State[System State<br/>Resources]
|
||
end
|
||
|
||
subgraph "Episodic Memory"
|
||
Actions[Past Actions<br/>Commands History]
|
||
Results[Action Results<br/>Outcomes]
|
||
Patterns[Success Patterns<br/>Best Practices]
|
||
end
|
||
|
||
Context --> |Query| VS
|
||
VS --> |Retrieve| Context
|
||
|
||
Goals --> |Consult| KB
|
||
KB --> |Guide| Goals
|
||
|
||
State --> |Record| Actions
|
||
Actions --> |Learn| Patterns
|
||
Patterns --> |Store| VS
|
||
|
||
Tools --> |Inform| State
|
||
Results --> |Update| Tools
|
||
|
||
VS --> |Enhance| KB
|
||
KB --> |Index| VS
|
||
|
||
classDef ltm fill:#f9f,stroke:#333,stroke-width:2px,color:#000
|
||
classDef wm fill:#bbf,stroke:#333,stroke-width:2px,color:#000
|
||
classDef em fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||
|
||
class VS,KB,Tools ltm
|
||
class Context,Goals,State wm
|
||
class Actions,Results,Patterns em
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>链式摘要</b>（点击展开）</summary>
|
||
|
||
链式摘要（Chain Summarization）系统通过选择性摘要较早的消息来管理对话上下文的增长。这对于在保持对话连贯性的同时避免超出 token 限制至关重要。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Input Chain] --> B{Needs Summarization?}
|
||
B -->|No| C[Return Original Chain]
|
||
B -->|Yes| D[Convert to ChainAST]
|
||
D --> E[Apply Section Summarization]
|
||
E --> F[Process Oversized Pairs]
|
||
F --> G[Manage Last Section Size]
|
||
G --> H[Apply QA Summarization]
|
||
H --> I[Rebuild Chain with Summaries]
|
||
I --> J{Is New Chain Smaller?}
|
||
J -->|Yes| K[Return Optimized Chain]
|
||
J -->|No| C
|
||
|
||
classDef process fill:#bbf,stroke:#333,stroke-width:2px,color:#000
|
||
classDef decision fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||
classDef output fill:#fbb,stroke:#333,stroke-width:2px,color:#000
|
||
|
||
class A,D,E,F,G,H,I process
|
||
class B,J decision
|
||
class C,K output
|
||
```
|
||
|
||
该算法作用于对话链的结构化表示（ChainAST），保留包括工具调用及其响应在内的消息类型。所有摘要操作在缩减上下文大小的同时保持关键对话流程。
|
||
|
||
### 全局摘要器配置选项
|
||
|
||
| 参数 | 环境变量 | 默认值 | 说明 |
|
||
| --------------------- | -------------------------------- | ------- | ---------------------------------------------------------- |
|
||
| 保留最后一段 | `SUMMARIZER_PRESERVE_LAST` | `true` | 是否完整保留最后一段中的所有消息 |
|
||
| 使用 QA 配对 | `SUMMARIZER_USE_QA` | `true` | 是否使用 QA 配对摘要策略 |
|
||
| 摘要 QA 中的人类消息 | `SUMMARIZER_SUM_MSG_HUMAN_IN_QA` | `false` | 是否对 QA 配对中的人类消息进行摘要 |
|
||
| 最后一段大小 | `SUMMARIZER_LAST_SEC_BYTES` | `51200` | 最后一段的最大字节大小（50KB） |
|
||
| 最大正文配对大小 | `SUMMARIZER_MAX_BP_BYTES` | `16384` | 单个正文配对的最大字节大小（16KB） |
|
||
| 最大 QA 段数 | `SUMMARIZER_MAX_QA_SECTIONS` | `10` | 最多保留的 QA 配对段数 |
|
||
| 最大 QA 大小 | `SUMMARIZER_MAX_QA_BYTES` | `65536` | QA 配对段的最大字节大小（64KB） |
|
||
| 保留 QA 段数 | `SUMMARIZER_KEEP_QA_SECTIONS` | `1` | 保留最近 QA 段的数量（不进行摘要） |
|
||
|
||
### Assistant 摘要器配置选项
|
||
|
||
Assistant 实例可使用自定义摘要设置来微调上下文管理行为：
|
||
|
||
| 参数 | 环境变量 | 默认值 | 说明 |
|
||
| ------------------ | --------------------------------------- | ------- | -------------------------------------------------------------------- |
|
||
| 保留最后一段 | `ASSISTANT_SUMMARIZER_PRESERVE_LAST` | `true` | 是否保留 assistant 最后一段中的所有消息 |
|
||
| 最后一段大小 | `ASSISTANT_SUMMARIZER_LAST_SEC_BYTES` | `76800` | assistant 最后一段的最大字节大小（75KB） |
|
||
| 最大 Body Pair 大小 | `ASSISTANT_SUMMARIZER_MAX_BP_BYTES` | `16384` | assistant 上下文中单个 body pair 的最大字节大小（16KB） |
|
||
| 最大 QA 段数 | `ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS` | `7` | 在 assistant 上下文中保留的最大 QA 段数 |
|
||
| 最大 QA 大小 | `ASSISTANT_SUMMARIZER_MAX_QA_BYTES` | `76800` | assistant QA 段的最大字节大小（75KB） |
|
||
| 保留 QA 段数 | `ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS` | `3` | 不进行摘要而保留的最近 QA 段数量 |
|
||
|
||
与全局设置相比，assistant 摘要器配置为上下文保留提供更多内存，在保留更多近期对话历史的同时仍确保高效的 token 使用。
|
||
|
||
### 摘要器环境配置
|
||
|
||
```bash
|
||
# Default values for global summarizer logic
|
||
SUMMARIZER_PRESERVE_LAST=true
|
||
SUMMARIZER_USE_QA=true
|
||
SUMMARIZER_SUM_MSG_HUMAN_IN_QA=false
|
||
SUMMARIZER_LAST_SEC_BYTES=51200
|
||
SUMMARIZER_MAX_BP_BYTES=16384
|
||
SUMMARIZER_MAX_QA_SECTIONS=10
|
||
SUMMARIZER_MAX_QA_BYTES=65536
|
||
SUMMARIZER_KEEP_QA_SECTIONS=1
|
||
|
||
# Default values for assistant summarizer logic
|
||
ASSISTANT_SUMMARIZER_PRESERVE_LAST=true
|
||
ASSISTANT_SUMMARIZER_LAST_SEC_BYTES=76800
|
||
ASSISTANT_SUMMARIZER_MAX_BP_BYTES=16384
|
||
ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS=7
|
||
ASSISTANT_SUMMARIZER_MAX_QA_BYTES=76800
|
||
ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS=3
|
||
```
|
||
|
||
</details>
|
||
|
||
<a id="advanced-agent-supervision"></a>
|
||
<details>
|
||
<summary><b>高级 Agent 监管</b>（点击展开）</summary>
|
||
|
||
PentAGI 包含复杂的多层 agent 监管机制，以确保高效的任务执行、防止无限循环，并在陷入卡住状态时提供智能恢复：
|
||
|
||
### 执行监控（Beta）
|
||
- **自动 Mentor 干预**：当执行模式表明可能存在问题时，会自动调用 Adviser agent（mentor）
|
||
- **模式检测**：监控相同的工具调用（阈值：5，可配置）和工具调用总数（阈值：10，可配置）
|
||
- **进度分析**：评估 agent 是否朝着子任务目标推进，检测循环和低效情况
|
||
- **替代策略**：当前策略失败时推荐不同方法
|
||
- **信息检索指导**：建议搜索已有解决方案，而非重新发明
|
||
- **增强响应格式**：工具响应同时包含 `<original_result>` 和 `<mentor_analysis>` 段
|
||
- **可配置**：通过 `EXECUTION_MONITOR_ENABLED` 启用（默认：false），使用 `EXECUTION_MONITOR_SAME_TOOL_LIMIT` 和 `EXECUTION_MONITOR_TOTAL_TOOL_LIMIT` 自定义阈值
|
||
|
||
**最适合**：较小模型（< 32B 参数）、需要持续指导的复杂攻击场景、防止 agent 卡在单一方法上
|
||
|
||
**性能影响**：执行时间和 token 使用量增加 2-3 倍，但根据 Qwen3.5-27B-FP8 的测试，**结果质量提升 2 倍**
|
||
|
||
### 智能任务规划（Beta）
|
||
- **自动分解**：Planner（规划模式下的 adviser）在 specialist agent 开始工作前生成 3-7 个具体可执行的步骤
|
||
- **上下文感知计划**：通过 enricher agent 分析完整执行上下文以制定知情计划
|
||
- **结构化分配**：原始请求包装在 `<task_assignment>` 结构中，包含执行计划和指令
|
||
- **范围管理**：通过让 agent 仅专注于当前子任务来防止范围蔓延
|
||
- **增强指令**：计划突出关键操作、潜在陷阱和验证点
|
||
- **可配置**：通过 `AGENT_PLANNING_STEP_ENABLED` 启用（默认：false）
|
||
|
||
**最适合**：< 32B 参数的模型、复杂渗透测试工作流、提高复杂任务的成功率
|
||
|
||
**增强 Adviser 配置**：当 adviser agent 使用更强模型或增强设置时效果特别好。示例：对 adviser 使用相同基础模型并开启最大推理模式（参见 [`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)）可在相同模型架构下实现全面的任务分析和战略规划。
|
||
|
||
**性能影响**：增加规划开销，但显著提高完成率并减少冗余工作
|
||
|
||
### 工具调用限制（始终启用）
|
||
- **硬性限制**：无论监管模式状态如何，均可防止失控执行
|
||
- **按 Agent 类型区分**：
|
||
- 通用 agent（Assistant、Primary Agent、Pentester、Coder、Installer）：`MAX_GENERAL_AGENT_TOOL_CALLS`（默认：100）
|
||
- 受限 agent（Searcher、Enricher、Memorist、Generator、Reporter、Adviser、Reflector、Planner）：`MAX_LIMITED_AGENT_TOOL_CALLS`（默认：20）
|
||
- **优雅终止**：接近限制时 Reflector 引导 agent 正确完成
|
||
- **资源保护**：确保系统稳定并防止资源耗尽
|
||
|
||
### Reflector 集成（始终启用）
|
||
- **自动纠正**：LLM 在 3 次尝试后仍未能生成工具调用时触发
|
||
- **战略指导**：分析失败并引导 agent 正确使用工具或屏障工具（`done`、`ask`）
|
||
- **恢复机制**：根据特定失败模式提供上下文指导
|
||
- **限制执行**：达到工具调用限制时协调优雅终止
|
||
|
||
### 开源模型建议
|
||
|
||
**< 32B 参数模型必备**：
|
||
Qwen3.5-27B-FP8 的测试表明，对于较小的开源模型，同时启用执行监控和任务规划是**必不可少的**：
|
||
- **质量提升**：与无监管的基线执行相比，结果好 2 倍
|
||
- **循环预防**：显著减少无限循环和冗余工作
|
||
- **攻击多样性**：鼓励探索多种攻击向量，而非执着于单一方法
|
||
- **气隙部署**：在封闭网络环境中通过本地 LLM 推理实现生产级自主渗透测试
|
||
|
||
**权衡**：
|
||
- Token 消耗：由于 mentor/planner 调用增加 2-3 倍
|
||
- 执行时间：由于分析和规划步骤延长 2-3 倍
|
||
- 结果质量：完整性、准确性和攻击覆盖度提升 2 倍
|
||
- 模型要求：adviser 使用增强配置时效果最佳（更高推理参数、更强模型变体或不同模型）
|
||
|
||
**配置策略**：
|
||
为在较小模型上获得最佳性能，请为 adviser agent 配置增强设置：
|
||
- 使用相同模型并开启最大推理模式（示例：[`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml)）
|
||
- 或为 adviser 使用更强模型，同时为其他 agent 保留基础模型
|
||
- 根据任务复杂度和模型能力调整监控阈值
|
||
|
||
|
||
|
||
</details>
|
||
|
||
PentAGI 的架构设计为模块化、可扩展且安全。以下是关键组件：
|
||
|
||
1. **核心服务**
|
||
- Frontend UI：基于 React 的 Web 界面，使用 TypeScript 确保类型安全
|
||
- Backend API：基于 Go 的 REST 和 GraphQL API，支持 Bearer token 认证以实现程序化访问
|
||
- Vector Store：PostgreSQL 配合 pgvector 用于语义搜索和记忆存储
|
||
- Task Queue：异步任务处理系统，确保可靠运行
|
||
- AI Agent：多 agent 系统，具有专门角色以实现高效测试
|
||
|
||
2. **知识图谱（Knowledge Graph）**
|
||
- Graphiti：用于语义关系追踪与上下文理解的知识图谱 API
|
||
- Neo4j：用于存储和查询实体、操作与结果之间关系的图数据库
|
||
- 自动捕获智能体响应与工具执行，以构建全面的知识库
|
||
|
||
3. **监控栈（Monitoring Stack）**
|
||
- OpenTelemetry：统一的可观测性数据采集与关联
|
||
- Grafana：实时可视化与告警仪表板
|
||
- VictoriaMetrics：高性能时序指标存储
|
||
- Jaeger：用于调试的端到端分布式追踪
|
||
- Loki：可扩展的日志聚合与分析
|
||
|
||
4. **分析平台（Analytics Platform）**
|
||
- Langfuse：高级 LLM 可观测性与性能分析
|
||
- ClickHouse：面向列的分析型数据仓库
|
||
- Redis：高速缓存与速率限制
|
||
- MinIO：用于存储产物的 S3 兼容对象存储
|
||
|
||
5. **安全工具（Security Tools）**
|
||
- Web Scraper：用于安全网页交互的隔离浏览器环境
|
||
- Pentesting Tools：包含 20+ 款专业安全工具的综合套件
|
||
- Sandboxed Execution：所有操作均在隔离容器中运行
|
||
|
||
6. **记忆系统（Memory Systems）**
|
||
- Long-term Memory：知识与经验的持久化存储
|
||
- Working Memory：当前操作的活跃上下文与目标
|
||
- Episodic Memory：历史操作与成功模式
|
||
- Knowledge Base：结构化的领域专业知识与工具能力
|
||
- Context Management：通过链式摘要智能管理不断增长的 LLM 上下文窗口
|
||
|
||
系统使用 Docker 容器实现隔离与便捷部署，为核心服务、监控和分析划分独立网络，以确保适当的安全边界。每个组件均支持水平扩展，并可针对生产环境配置为高可用。
|
||
|
||
## 快速开始
|
||
|
||
### 系统要求
|
||
|
||
- Docker 与 Docker Compose（或 Podman — 参见 [Podman 配置](#running-pentagi-with-podman)）
|
||
- 至少 2 个 vCPU
|
||
- 至少 4GB RAM
|
||
- 20GB 可用磁盘空间
|
||
- 可访问互联网以下载镜像与更新
|
||
|
||
### 使用安装程序（推荐）
|
||
|
||
PentAGI 提供带终端界面的交互式安装程序，用于简化配置与部署。安装程序会引导你完成系统检查、LLM 提供商设置、搜索引擎配置以及安全加固。
|
||
|
||
**支持的平台：**
|
||
- **Linux**：amd64 [download](https://pentagi.com/downloads/linux/amd64/installer-latest.zip) | arm64 [download](https://pentagi.com/downloads/linux/arm64/installer-latest.zip)
|
||
- **Windows**：amd64 [download](https://pentagi.com/downloads/windows/amd64/installer-latest.zip)
|
||
- **macOS**：amd64 (Intel) [download](https://pentagi.com/downloads/darwin/amd64/installer-latest.zip) | arm64 (M-series) [download](https://pentagi.com/downloads/darwin/arm64/installer-latest.zip)
|
||
|
||
**快速安装（Linux amd64）：**
|
||
|
||
```bash
|
||
# Create installation directory
|
||
mkdir -p pentagi && cd pentagi
|
||
|
||
# Download installer
|
||
wget -O installer.zip https://pentagi.com/downloads/linux/amd64/installer-latest.zip
|
||
|
||
# Extract
|
||
unzip installer.zip
|
||
|
||
# Run interactive installer
|
||
./installer
|
||
```
|
||
|
||
**前提条件与权限：**
|
||
|
||
安装程序需要适当权限以与 Docker API 交互，从而正常运行。默认情况下，它使用 Docker 套接字（`/var/run/docker.sock`），这需要满足以下任一条件：
|
||
|
||
- **选项 1（生产环境推荐）：** 以 root 身份运行安装程序：
|
||
```bash
|
||
sudo ./installer
|
||
```
|
||
|
||
- **选项 2（开发环境）：** 将用户加入 `docker` 组，以授予其对 Docker 套接字的访问权限：
|
||
```bash
|
||
# Add your user to the docker group
|
||
sudo usermod -aG docker $USER
|
||
|
||
# Log out and log back in, or activate the group immediately
|
||
newgrp docker
|
||
|
||
# Verify Docker access (should run without sudo)
|
||
docker ps
|
||
```
|
||
|
||
⚠️ **安全提示：** 将用户加入 `docker` 组会授予与 root 等效的权限。仅在受控环境中的可信用户上执行此操作。对于生产部署，请考虑使用 rootless Docker 模式，或以 sudo 运行安装程序。
|
||
|
||
安装程序将执行以下步骤：
|
||
1. **系统检查**：验证 Docker、网络连接与系统要求
|
||
2. **环境设置**：创建并配置 `.env` 文件，采用最优默认值
|
||
3. **提供商配置**：设置 LLM 提供商（OpenAI、Anthropic、Gemini、Bedrock、Ollama、Custom）
|
||
4. **搜索引擎**：配置 DuckDuckGo、Google、Tavily、Traversaal、Perplexity、Sploitus、Searxng
|
||
5. **安全加固**：生成安全凭据并配置 SSL 证书
|
||
6. **部署**：使用 docker-compose 启动 PentAGI
|
||
|
||
### 当前 Web 设置覆盖范围
|
||
|
||
PentAGI Web 控制台在服务器启动运行后，已可管理多个设置区域：
|
||
|
||
- **Settings -> Providers**：为支持的提供商类型创建、编辑、删除并测试用户自定义的提供商配置文件。这些配置文件控制每个智能体的模型选择、运行时参数、推理选项以及定价元数据。
|
||
- **Settings -> Prompts**：管理系统、人类与工具提示词模板。
|
||
- **Settings -> PentAGI API**：创建并管理用于 REST 与 GraphQL 访问的 PentAGI Bearer 令牌。
|
||
- **其他由 UI 管理的偏好设置**：收藏流程以用户偏好形式存储，主题选择由主侧边栏/个人资料控件处理，而非 Settings 页面。
|
||
|
||
### 仍由服务器管理
|
||
|
||
以下配置区域仍需通过环境变量、compose 文件或挂载的配置文件在服务器端设置：
|
||
|
||
- **LLM 凭据与连接详情**：OpenAI、Anthropic、Bedrock、Ollama、自定义提供商及类似后端的 API 密钥、端点、认证模式与提供商特定连接设置；config-path 设置仅在受支持的场景下适用，例如 `OLLAMA_SERVER_CONFIG_PATH` 与 `LLM_SERVER_CONFIG_PATH`。
|
||
- **搜索提供商凭据与选项**：如 `DUCKDUCKGO_*`、`GOOGLE_*`、`TAVILY_API_KEY`、`TRAVERSAAL_API_KEY`、`PERPLEXITY_*`、`SEARXNG_*` 以及 `SPLOITUS_ENABLED` 等设置。
|
||
- **第三方集成**：Langfuse、Graphiti 及类似外部服务仍为服务器端配置。
|
||
- **MCP 服务器管理**：MCP 设置页面目前尚未作为实时 Web 控制台功能开放。
|
||
|
||
**面向生产环境与增强安全性：**
|
||
|
||
对于生产部署或安全敏感环境，我们**强烈建议**采用分布式双节点架构，将 worker 操作隔离在独立服务器上。这可防止不可信代码执行与主系统上的网络访问问题。
|
||
|
||
**详见详细指南**：[Worker Node Setup](examples/guides/worker_node.md)
|
||
|
||
双节点部署提供：
|
||
- **隔离执行**：Worker 容器在专用硬件上运行
|
||
- **网络隔离**：渗透测试采用独立的网络边界
|
||
- **安全边界**：带 TLS 认证的 Docker-in-Docker
|
||
- **OOB 攻击支持**：为带外（out-of-band）技术提供专用端口范围
|
||
|
||
### 手动安装
|
||
|
||
1. 创建工作目录或克隆仓库：
|
||
|
||
```bash
|
||
mkdir pentagi && cd pentagi
|
||
```
|
||
|
||
2. 将 `.env.example` 复制为 `.env`，或下载它：
|
||
|
||
```bash
|
||
curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example
|
||
```
|
||
|
||
3. 创建示例文件（`example.custom.provider.yml`、`example.ollama.provider.yml`），或下载它：
|
||
|
||
```bash
|
||
curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/custom-openai.provider.yml
|
||
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/ollama-llama318b.provider.yml
|
||
```
|
||
|
||
4. 在 `.env` 文件中填写所需的 API 密钥。
|
||
|
||
```bash
|
||
# Required: At least one of these LLM providers
|
||
OPEN_AI_KEY=your_openai_key
|
||
ANTHROPIC_API_KEY=your_anthropic_key
|
||
GEMINI_API_KEY=your_gemini_key
|
||
|
||
# Optional: AWS Bedrock provider (enterprise-grade models)
|
||
BEDROCK_REGION=us-east-1
|
||
# Choose one authentication method:
|
||
BEDROCK_DEFAULT_AUTH=true # Option 1: Use AWS SDK default credential chain (recommended for EC2/ECS)
|
||
# BEDROCK_BEARER_TOKEN=your_bearer_token # Option 2: Bearer token authentication
|
||
# BEDROCK_ACCESS_KEY_ID=your_aws_access_key # Option 3: Static credentials
|
||
# BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
|
||
|
||
# Optional: Ollama provider (local or cloud)
|
||
# OLLAMA_SERVER_URL=http://ollama-server:11434 # Local server
|
||
# OLLAMA_SERVER_URL=https://ollama.com # Cloud service
|
||
# OLLAMA_SERVER_API_KEY=your_ollama_cloud_key # Required for cloud, empty for local
|
||
|
||
# Optional: Chinese AI providers
|
||
# DEEPSEEK_API_KEY=your_deepseek_key # DeepSeek (strong reasoning)
|
||
# GLM_API_KEY=your_glm_key # GLM (Zhipu AI)
|
||
# KIMI_API_KEY=your_kimi_key # Kimi (Moonshot AI, ultra-long context)
|
||
# QWEN_API_KEY=your_qwen_key # Qwen (Alibaba Cloud, multimodal)
|
||
|
||
# Optional: Local LLM provider (zero-cost inference)
|
||
OLLAMA_SERVER_URL=http://localhost:11434
|
||
OLLAMA_SERVER_MODEL=your_model_name
|
||
|
||
# Optional: Additional search capabilities
|
||
DUCKDUCKGO_ENABLED=true
|
||
DUCKDUCKGO_REGION=us-en
|
||
DUCKDUCKGO_SAFESEARCH=
|
||
DUCKDUCKGO_TIME_RANGE=
|
||
SPLOITUS_ENABLED=true
|
||
GOOGLE_API_KEY=your_google_key
|
||
GOOGLE_CX_KEY=your_google_cx
|
||
TAVILY_API_KEY=your_tavily_key
|
||
TRAVERSAAL_API_KEY=your_traversaal_key
|
||
PERPLEXITY_API_KEY=your_perplexity_key
|
||
PERPLEXITY_MODEL=sonar-pro
|
||
PERPLEXITY_CONTEXT_SIZE=medium
|
||
|
||
# Searxng meta search engine (aggregates results from multiple sources)
|
||
SEARXNG_URL=http://your-searxng-instance:8080
|
||
SEARXNG_CATEGORIES=general
|
||
SEARXNG_LANGUAGE=
|
||
SEARXNG_SAFESEARCH=0
|
||
SEARXNG_TIME_RANGE=
|
||
SEARXNG_TIMEOUT=
|
||
|
||
## Graphiti knowledge graph settings
|
||
GRAPHITI_ENABLED=true
|
||
GRAPHITI_TIMEOUT=30
|
||
GRAPHITI_URL=http://graphiti:8000
|
||
GRAPHITI_MODEL_NAME=gpt-5-mini
|
||
|
||
# Neo4j settings (used by Graphiti stack)
|
||
NEO4J_USER=neo4j
|
||
NEO4J_DATABASE=neo4j
|
||
NEO4J_PASSWORD=devpassword
|
||
NEO4J_URI=bolt://neo4j:7687
|
||
|
||
# Assistant configuration
|
||
ASSISTANT_USE_AGENTS=false # Default value for agent usage when creating new assistants
|
||
```
|
||
|
||
5. 修改 `.env` 文件中所有与安全相关的环境变量，以提升安全性。
|
||
|
||
<details>
|
||
<summary>与安全相关的环境变量</summary>
|
||
|
||
### 主要安全设置
|
||
- `COOKIE_SIGNING_SALT` - 用于 Cookie 签名的盐值，请改为随机值
|
||
- `PUBLIC_URL` - 服务器的公开 URL（例如 `https://pentagi.example.com`）
|
||
- `SERVER_SSL_CRT` 和 `SERVER_SSL_KEY` - 现有 SSL 证书与密钥的自定义路径，用于 HTTPS（这些路径应在 docker-compose.yml 文件中作为卷挂载使用）
|
||
|
||
### 爬虫（Scraper）访问
|
||
- `SCRAPER_PUBLIC_URL` - 若要为公开 URL 使用不同的爬虫服务器，请设置爬虫的公开 URL
|
||
- `SCRAPER_PRIVATE_URL` - 爬虫的私有 URL（docker-compose.yml 文件中的本地爬虫服务器，用于访问本地 URL）
|
||
|
||
### 访问凭据
|
||
- `PENTAGI_POSTGRES_USER` 和 `PENTAGI_POSTGRES_PASSWORD` - PostgreSQL 凭据
|
||
- `NEO4J_USER` 和 `NEO4J_PASSWORD` - Neo4j 凭据（用于 Graphiti 知识图谱）
|
||
|
||
</details>
|
||
|
||
6. 若要在 VSCode 或其他 IDE 中将其作为 envFile 选项使用，请移除 `.env` 文件中的所有行内注释：
|
||
|
||
```bash
|
||
perl -i -pe 's/\s+#.*$//' .env
|
||
```
|
||
|
||
7. 运行 PentAGI 栈：
|
||
|
||
```bash
|
||
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml
|
||
docker compose up -d
|
||
```
|
||
|
||
访问 [localhost:8443](https://localhost:8443) 以打开 PentAGI Web UI（默认为 `admin@pentagi.com` / `admin`）
|
||
|
||
#### Web UI 账户
|
||
|
||
PentAGI 不会在登录页提供公开的自助注册。全新安装会创建默认的本地管理员账户：
|
||
|
||
- **Email**：`admin@pentagi.com`
|
||
- **Password**：`admin`
|
||
|
||
首次登录时，请在使用该实例进行实际工作前修改默认密码。若之后遗失管理员密码，可使用安装程序的维护菜单重置默认 `admin@pentagi.com` 账户密码。
|
||
|
||
对于多用户部署，已认证的管理员可通过 Users REST API（`/api/v1/users/`）管理本地用户。实例运行后，可在 `https://localhost:8443/api/v1/swagger/index.html` 访问 OpenAPI UI。
|
||
|
||
> [!NOTE]
|
||
> 若遇到与 `pentagi-network`、`observability-network` 或 `langfuse-network` 相关的错误，需先运行 `docker-compose.yml` 以创建这些网络，然后再运行 `docker-compose-langfuse.yml`、`docker-compose-graphiti.yml` 和 `docker-compose-observability.yml`，才能使用 Langfuse、Graphiti 和 Observability 服务。
|
||
>
|
||
> 必须至少配置一个语言模型（Language Model）提供商（OpenAI、Anthropic、Gemini、AWS Bedrock 或 Ollama）才能使用 PentAGI。AWS Bedrock 提供企业级访问，可调用多家领先 AI 公司的基础模型；若具备足够的计算资源，Ollama 可提供零成本的本地推理。搜索引擎的额外 API 密钥为可选项，但建议配置以获得更好效果。
|
||
>
|
||
> **完全本地部署并使用高级模型**：请参阅我们的完整指南 [使用 vLLM 与 Qwen3.5-27B-FP8 运行 PentAGI](examples/guides/vllm-qwen35-27b-fp8.md)，了解生产级本地 LLM 配置。该方案在 4× RTX 5090 GPU 上可实现约 13,000 TPS 的提示处理吞吐与约 650 TPS 的补全吞吐，支持 12+ 个并发流程，且完全不依赖云服务商。
|
||
>
|
||
> `LLM_SERVER_*` 环境变量为实验性功能，未来可能会变更。目前可用它们指定自定义 LLM 服务器 URL，并为所有智能体类型指定同一模型。
|
||
>
|
||
> `PROXY_URL` 是所有 LLM 提供商与外部搜索系统的全局代理 URL，可用于与外部网络隔离。
|
||
>
|
||
> `docker-compose.yml` 文件以 root 用户运行 PentAGI 服务，因为需要访问 docker.sock 以管理容器。若使用 TCP/IP 网络连接 Docker 而非套接字文件，可移除 root 权限，改用默认的 `pentagi` 用户以提升安全性。
|
||
|
||
### 从外部网络访问 PentAGI
|
||
|
||
默认情况下，PentAGI 绑定到 `127.0.0.1`（仅 localhost），以确保安全。若要从网络中的其他机器访问 PentAGI，需要配置外部访问。
|
||
|
||
#### 配置步骤
|
||
|
||
1. **更新 `.env` 文件**，填入服务器的 IP 地址：
|
||
|
||
```bash
|
||
# Network binding - allow external connections
|
||
PENTAGI_LISTEN_IP=0.0.0.0
|
||
PENTAGI_LISTEN_PORT=8443
|
||
|
||
# Public URL - use your actual server IP or hostname
|
||
# Replace 192.168.1.100 with your server's IP address
|
||
PUBLIC_URL=https://192.168.1.100:8443
|
||
|
||
# CORS origins - list all URLs that will access PentAGI
|
||
# Include localhost for local access AND your server IP for external access
|
||
CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443
|
||
```
|
||
|
||
> [!IMPORTANT]
|
||
> - 将 `192.168.1.100` 替换为服务器的实际 IP 地址
|
||
> - 不要在 `PUBLIC_URL` 或 `CORS_ORIGINS` 中使用 `0.0.0.0` —— 应使用实际 IP 地址
|
||
> - 在 `CORS_ORIGINS` 中同时包含 localhost 与服务器 IP，以便灵活使用
|
||
|
||
2. **重新创建容器**以应用更改：
|
||
|
||
```bash
|
||
docker compose down
|
||
docker compose up -d --force-recreate
|
||
```
|
||
|
||
3. **验证端口绑定：**
|
||
|
||
```bash
|
||
docker ps | grep pentagi
|
||
```
|
||
|
||
应看到 `0.0.0.0:8443->8443/tcp` 或 `:::8443->8443/tcp`。
|
||
|
||
若看到 `127.0.0.1:8443->8443/tcp`，说明环境变量未被读取。此时请直接编辑 `docker-compose.yml` 第 31 行：
|
||
|
||
```yaml
|
||
ports:
|
||
- "0.0.0.0:8443:8443"
|
||
```
|
||
|
||
然后再次重新创建容器。
|
||
|
||
4. **配置防火墙**，允许 8443 端口的入站连接：
|
||
|
||
```bash
|
||
# Ubuntu/Debian with UFW
|
||
sudo ufw allow 8443/tcp
|
||
sudo ufw reload
|
||
|
||
# CentOS/RHEL with firewalld
|
||
sudo firewall-cmd --permanent --add-port=8443/tcp
|
||
sudo firewall-cmd --reload
|
||
```
|
||
|
||
5. **访问 PentAGI：**
|
||
|
||
- **本地访问：** `https://localhost:8443`
|
||
- **网络访问：** `https://your-server-ip:8443`
|
||
|
||
> [!NOTE]
|
||
> 通过 IP 地址访问时，需要在浏览器中接受自签名 SSL 证书警告。
|
||
|
||
---
|
||
|
||
### 使用 Podman 运行 PentAGI
|
||
|
||
PentAGI 完全支持 Podman 作为 Docker 的替代方案。但在使用 **Podman 无根（rootless）模式**时，爬虫服务需要特殊配置，因为无根容器无法绑定特权端口（1024 以下端口）。
|
||
|
||
#### Podman 无根模式配置
|
||
|
||
默认爬虫配置使用 443 端口（HTTPS），属于特权端口。对于 Podman 无根模式，需将爬虫重新配置为使用非特权端口：
|
||
|
||
**1. 编辑 `docker-compose.yml`** —— 修改 `scraper` 服务（约第 199 行）：
|
||
|
||
```yaml
|
||
scraper:
|
||
image: vxcontrol/scraper:latest
|
||
restart: unless-stopped
|
||
container_name: scraper
|
||
hostname: scraper
|
||
expose:
|
||
- 3000/tcp # Changed from 443 to 3000
|
||
ports:
|
||
- "${SCRAPER_LISTEN_IP:-127.0.0.1}:${SCRAPER_LISTEN_PORT:-9443}:3000" # Map to port 3000
|
||
environment:
|
||
- MAX_CONCURRENT_SESSIONS=${LOCAL_SCRAPER_MAX_CONCURRENT_SESSIONS:-10}
|
||
- USERNAME=${LOCAL_SCRAPER_USERNAME:-someuser}
|
||
- PASSWORD=${LOCAL_SCRAPER_PASSWORD:-somepass}
|
||
logging:
|
||
options:
|
||
max-size: 50m
|
||
max-file: "7"
|
||
volumes:
|
||
- scraper-ssl:/usr/src/app/ssl
|
||
networks:
|
||
- pentagi-network
|
||
shm_size: 2g
|
||
```
|
||
|
||
**2. 更新 `.env` 文件** —— 将爬虫 URL 改为使用 HTTP 与 3000 端口：
|
||
|
||
```bash
|
||
# Scraper configuration for Podman rootless
|
||
SCRAPER_PRIVATE_URL=http://someuser:somepass@scraper:3000/
|
||
LOCAL_SCRAPER_USERNAME=someuser
|
||
LOCAL_SCRAPER_PASSWORD=somepass
|
||
```
|
||
|
||
> [!IMPORTANT]
|
||
> Podman 的关键变更：
|
||
> - `SCRAPER_PRIVATE_URL` 使用 **HTTP** 而非 HTTPS
|
||
> - 使用端口 **3000** 而非 443
|
||
> - 将内部 `expose` 改为 `3000/tcp`
|
||
> - 将端口映射目标从 `443` 更新为 `3000`
|
||
|
||
**3. 重新创建容器：**
|
||
|
||
```bash
|
||
podman-compose down
|
||
podman-compose up -d --force-recreate
|
||
```
|
||
|
||
**4. 测试爬虫连通性：**
|
||
|
||
```bash
|
||
# Test from within the pentagi container
|
||
podman exec -it pentagi wget -O- "http://someuser:somepass@scraper:3000/html?url=http://example.com"
|
||
```
|
||
|
||
若看到 HTML 输出，说明爬虫工作正常。
|
||
|
||
#### Podman 有根（Rootful）模式
|
||
|
||
若以有根模式运行 Podman（使用 sudo），可使用默认配置而无需修改。爬虫将按预期在 443 端口上工作。
|
||
|
||
#### Docker 兼容性
|
||
|
||
所有 Podman 配置与 Docker 完全兼容。非特权端口方案在两种容器运行时上的工作方式相同。
|
||
|
||
### 助手配置
|
||
|
||
PentAGI 允许你为助手配置默认行为：
|
||
|
||
| Variable | Default | Description |
|
||
| ---------------------- | ------- | ----------------------------------------------------------------------- |
|
||
| `ASSISTANT_USE_AGENTS` | `false` | 控制创建新助手时代理（agent）用量的默认值 |
|
||
|
||
`ASSISTANT_USE_AGENTS` 设置会影响在 UI 中创建新助手时「Use Agents」开关的初始状态：
|
||
- `false`（默认）：新助手默认创建时禁用代理委派
|
||
- `true`：新助手默认创建时启用代理委派
|
||
|
||
请注意，用户在创建或编辑助手时，始终可以通过 UI 中的「Use Agents」按钮覆盖此设置。该环境变量仅控制初始默认状态。
|
||
|
||
## 登录后如何使用 PentAGI
|
||
|
||
堆栈运行且你可以登录 Web UI 后，最快的入门方式是通过 Flows 工作流。
|
||
|
||
### 1. 创建你的第一个 flow
|
||
|
||
1. 在侧边栏中打开 **Flows**。
|
||
2. 点击 **New Flow**。
|
||
3. 选择符合你目标的运行模式：
|
||
- **Automation**：针对你希望 PentAGI 端到端完成的测试目标，进行完全自主执行
|
||
- **Assistant**：当你希望逐步引导调查时，进行交互式来回协助。在此模式下，你还可以启用 **Use Agents** 开关，让 PentAGI 将子任务委派给专门的子代理（sub-agent），以应对更复杂的调查。
|
||
4. 选择要用于此 flow 的 LLM 提供商。
|
||
5. 在消息框中用自然语言描述目标与目的。
|
||
|
||
良好的首个提示通常包括：
|
||
|
||
- 目标系统或 URL
|
||
- 你想要的评估类型
|
||
- 任何范围限制或交战规则（rules of engagement）
|
||
- 你期望的结果，例如漏洞报告或对假设的验证
|
||
|
||
示例：
|
||
|
||
```text
|
||
Assess https://target.example for common web application vulnerabilities. Focus on authentication, file handling, and injection issues. Stay within the provided target only and summarize confirmed findings with reproduction steps.
|
||
```
|
||
|
||
仅测试你拥有或已获明确授权评估的系统。可接受使用要求请参阅 [EULA.md](EULA.md)。
|
||
|
||
### 2. 使用模板实现可重复的工作流
|
||
|
||
新建 flow 表单包含模板选择器，可用已保存的 flow 模板预填消息框。当你反复运行类似评估时，这很有用。
|
||
|
||
- 若你已在 **Templates** 中保存模板，可使用现有模板
|
||
- 若需要 Web 测试的实用基线，可从 [`examples/prompts/base_web_pentest.md`](examples/prompts/base_web_pentest.md) 中的示例提示入手
|
||
- 启动 flow 前，请调整目标、范围和约束
|
||
|
||
模板只是起点。使用 PentAGI 无需特殊语法：只要目标与目的清晰，纯自然语言指令即可良好工作。
|
||
|
||
### 3. 监控执行并审阅输出
|
||
|
||
提交 flow 后，PentAGI 会自动打开 flow 页面。
|
||
|
||
- 使用主 flow 视图跟踪消息、代理活动与任务进度
|
||
- 在 flow 运行期间检查工具活动与终端输出
|
||
- 审阅生成的任务与子任务，以了解 PentAGI 正在做什么
|
||
|
||
当 flow 已有足够结果时，使用 flow 页面上的 **Report** 菜单可：
|
||
|
||
- 在 Web 视图中打开报告
|
||
- 将生成的报告复制到剪贴板
|
||
- 将报告下载为 Markdown
|
||
- 将报告下载为 PDF
|
||
|
||
### 4. 使用 Assistant 视图引导活跃的 flow
|
||
|
||
每个 flow 还包含用于交互式引导的 **Assistant** 视图。当自主运行发现需要人工指引而非硬性重启的情况时，这很有用。
|
||
|
||
- 在更改任何内容之前，若你想检查当前状态，请为同一 flow 打开 **Assistant** 视图。
|
||
- 使用助手检查 flow 状态、停止当前任务、提交后续指令，或在下一步运行前修补剩余计划子任务。
|
||
- 将其视为当前 flow 的显式控制路径，而非不可见的后台队列。若要改变方向，请明确说明，并使新指令与当前交战范围保持一致。
|
||
- 这最适合澄清范围、在中间发现后重定向优先级，或在不丢失其余 flow 上下文的情况下响应自动化检查点。
|
||
|
||
### 5. 管理 flow 范围内的文件
|
||
|
||
每个 flow 在 flow 页面都有各自的 **Files** 标签页。文件限定于父 flow：它们位于主机上的 `{dataDir}/flow-{id}-data/`，且绝不会泄漏到其他 flow。
|
||
|
||
该标签页展示三类文件来源：
|
||
|
||
- **Uploads**（`uploads/`）：你从 Web UI 提供的文件。使用 **Upload files** 操作，或直接拖放到 Files 标签页。代理容器运行时，上传的文件也会推送到其中的 `/work/uploads/`，以便代理用常规 shell 工具读取。
|
||
- **Resources**（`resources/`）：通过 **Attach resources from library** 从你已保存的用户资源库附加的文件。附加的资源会复制到 flow，并推送到运行中容器的 `/work/resources/`。
|
||
- **Container**（`container/`）：通过 **Pull file or directory from container** 从运行中的代理容器拉取的快照。它们在 flow 侧为只读，且绝不会发回容器。
|
||
|
||
Files 标签页中每个文件的操作包括 **Download**、**Copy path**、**Save as resource**（将 flow 文件提升到你可复用的资源库），以及 **Delete**。容器未运行时 Pull 操作会被禁用，工具提示为「Container is not running」。
|
||
|
||
上传的文件与附加资源会通过 `{{.UserFiles}}` 模板变量自动列在代理的系统提示中，该变量会渲染紧凑的 `<task_files>` XML 块（含嵌套的 `<uploads>` 与 `<resources>` 节），以便助手与自动化代理按路径引用它们，而无需你将内容粘贴到聊天中。容器快照仅在 UI 中可见，不会自动注入回提示。
|
||
|
||
需注意的当前限制：
|
||
|
||
- 单文件最大上传大小为 300 MB；单次上传请求最多 1000 个文件、总计 2 GB。文件名上限为 255 字节（约 255 个 ASCII 字符；非 ASCII 名称每个字符占用多个字节）。
|
||
- 上传与资源会镜像到运行中容器的固定路径 `/work/uploads/` 与 `/work/resources/`；写入其他容器路径的文件不会自动镜像回 flow 文件模型。容器快照可来自你拉取的任意容器路径（例如 `/etc/...`），并在 flow 侧缓存于 `container/` 下；它们不会推回容器。
|
||
- 容器快照为时间点拉取。在 UI 中编辑快照不会写回运行中的容器。
|
||
- 目前删除 flow 会移除 flow 记录及其长期记忆条目，但尚未归档或删除磁盘上该 flow 的 `flow-{id}-data/` 目录。若运维人员希望回收空间，仍需手动清理数据目录。
|
||
|
||
早期测试时，请从狭窄目标与单一清晰目的入手。这样输出更易审阅，也有助于在运行更大规模评估前优化提示。
|
||
|
||
## API 访问
|
||
|
||
PentAGI 通过 REST 与 GraphQL API 提供全面的程序化访问，使你能够将渗透测试工作流集成到自动化流水线、CI/CD 流程与自定义应用中。
|
||
|
||
### 生成 API 令牌
|
||
|
||
API 令牌通过 PentAGI Web 界面管理：
|
||
|
||
1. 在 Web UI 中导航至 **Settings** → **API Tokens**
|
||
2. 点击 **Create Token** 生成新的 API 令牌
|
||
3. 配置令牌属性：
|
||
- **Name**（可选）：令牌的描述性名称
|
||
- **Expiration Date**：令牌过期时间（最短 1 分钟，最长 3 年）
|
||
4. 点击 **Create** 并**立即复制令牌**——出于安全考虑，令牌仅显示一次
|
||
5. 在 API 请求中将该令牌用作 Bearer 令牌
|
||
|
||
每个令牌均与您的用户账户关联，并继承您角色所拥有的权限。
|
||
|
||
### 使用 API 令牌
|
||
|
||
在 HTTP 请求的 `Authorization` 请求头中包含 API 令牌：
|
||
|
||
```bash
|
||
# GraphQL API example
|
||
curl -X POST https://your-pentagi-instance:8443/api/v1/graphql \
|
||
-H "Authorization: Bearer YOUR_API_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"query": "{ flows { id title status } }"}'
|
||
|
||
# REST API example
|
||
curl https://your-pentagi-instance:8443/api/v1/flows \
|
||
-H "Authorization: Bearer YOUR_API_TOKEN"
|
||
```
|
||
|
||
### API 探索与测试
|
||
|
||
PentAGI 提供交互式文档，用于探索和测试 API 端点：
|
||
|
||
#### GraphQL Playground
|
||
|
||
在 `https://your-pentagi-instance:8443/api/v1/graphql/playground` 访问 GraphQL Playground
|
||
|
||
1. 点击底部的 **HTTP Headers** 标签页
|
||
2. 添加您的授权请求头：
|
||
```json
|
||
{
|
||
"Authorization": "Bearer YOUR_API_TOKEN"
|
||
}
|
||
```
|
||
3. 交互式地探索 schema、运行查询并测试变更（mutation）
|
||
|
||
#### Swagger UI
|
||
|
||
在 `https://your-pentagi-instance:8443/api/v1/swagger/index.html` 访问 REST API 文档
|
||
|
||
1. 点击 **Authorize** 按钮
|
||
2. 按以下格式输入您的令牌：`Bearer YOUR_API_TOKEN`
|
||
3. 点击 **Authorize** 以应用
|
||
4. 直接在 Swagger UI 中测试端点
|
||
|
||
### 生成 API 客户端
|
||
|
||
您可以使用 PentAGI 附带的 schema 文件，为偏好的编程语言生成类型安全的 API 客户端：
|
||
|
||
#### GraphQL 客户端
|
||
|
||
GraphQL schema 可通过以下方式获取：
|
||
- **Web UI**：前往 Settings 下载 `schema.graphqls`
|
||
- **直接文件**：仓库中的 `backend/pkg/graph/schema.graphqls`
|
||
|
||
可使用以下工具生成客户端：
|
||
- **GraphQL Code Generator**（JavaScript/TypeScript）：[https://the-guild.dev/graphql/codegen](https://the-guild.dev/graphql/codegen)
|
||
- **genqlient**（Go）：[https://github.com/Khan/genqlient](https://github.com/Khan/genqlient)
|
||
- **Apollo iOS**（Swift）：[https://www.apollographql.com/docs/ios](https://www.apollographql.com/docs/ios)
|
||
|
||
#### REST API 客户端
|
||
|
||
OpenAPI 规范可通过以下方式获取：
|
||
- **Swagger JSON**：`https://your-pentagi-instance:8443/api/v1/swagger/doc.json`
|
||
- **Swagger YAML**：可在 `backend/pkg/server/docs/swagger.yaml` 中获取
|
||
|
||
可使用以下工具生成客户端：
|
||
- **OpenAPI Generator**：[https://openapi-generator.tech](https://openapi-generator.tech)
|
||
```bash
|
||
openapi-generator-cli generate \
|
||
-i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
|
||
-g python \
|
||
-o ./pentagi-client
|
||
```
|
||
|
||
- **Swagger Codegen**：[https://github.com/swagger-api/swagger-codegen](https://github.com/swagger-api/swagger-codegen)
|
||
```bash
|
||
swagger-codegen generate \
|
||
-i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
|
||
-l typescript-axios \
|
||
-o ./pentagi-client
|
||
```
|
||
|
||
- **swagger-typescript-api**（TypeScript）：[https://github.com/acacode/swagger-typescript-api](https://github.com/acacode/swagger-typescript-api)
|
||
```bash
|
||
npx swagger-typescript-api \
|
||
-p https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
|
||
-o ./src/api \
|
||
-n pentagi-api.ts
|
||
```
|
||
|
||
### API 使用示例
|
||
|
||
<details>
|
||
<summary><b>创建新 Flow（GraphQL）</b></summary>
|
||
|
||
```graphql
|
||
mutation CreateFlow {
|
||
createFlow(
|
||
modelProvider: "openai"
|
||
input: "Test the security of https://example.com"
|
||
) {
|
||
id
|
||
title
|
||
status
|
||
createdAt
|
||
}
|
||
}
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>列出 Flow（REST API）</b></summary>
|
||
|
||
```bash
|
||
curl https://your-pentagi-instance:8443/api/v1/flows \
|
||
-H "Authorization: Bearer YOUR_API_TOKEN" \
|
||
| jq '.flows[] | {id, title, status}'
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Python 客户端示例</b></summary>
|
||
|
||
```python
|
||
import requests
|
||
|
||
class PentAGIClient:
|
||
def __init__(self, base_url, api_token):
|
||
self.base_url = base_url
|
||
self.headers = {
|
||
"Authorization": f"Bearer {api_token}",
|
||
"Content-Type": "application/json"
|
||
}
|
||
|
||
def create_flow(self, provider, target):
|
||
query = """
|
||
mutation CreateFlow($provider: String!, $input: String!) {
|
||
createFlow(modelProvider: $provider, input: $input) {
|
||
id
|
||
title
|
||
status
|
||
}
|
||
}
|
||
"""
|
||
response = requests.post(
|
||
f"{self.base_url}/api/v1/graphql",
|
||
json={
|
||
"query": query,
|
||
"variables": {
|
||
"provider": provider,
|
||
"input": target
|
||
}
|
||
},
|
||
headers=self.headers
|
||
)
|
||
return response.json()
|
||
|
||
def get_flows(self):
|
||
response = requests.get(
|
||
f"{self.base_url}/api/v1/flows",
|
||
headers=self.headers
|
||
)
|
||
return response.json()
|
||
|
||
# Usage
|
||
client = PentAGIClient(
|
||
"https://your-pentagi-instance:8443",
|
||
"your_api_token_here"
|
||
)
|
||
|
||
# Create a new flow
|
||
flow = client.create_flow("openai", "Scan https://example.com for vulnerabilities")
|
||
print(f"Created flow: {flow}")
|
||
|
||
# List all flows
|
||
flows = client.get_flows()
|
||
print(f"Total flows: {len(flows['flows'])}")
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>TypeScript 客户端示例</b></summary>
|
||
|
||
```typescript
|
||
import axios, { AxiosInstance } from 'axios';
|
||
|
||
interface Flow {
|
||
id: string;
|
||
title: string;
|
||
status: string;
|
||
createdAt: string;
|
||
}
|
||
|
||
class PentAGIClient {
|
||
private client: AxiosInstance;
|
||
|
||
constructor(baseURL: string, apiToken: string) {
|
||
this.client = axios.create({
|
||
baseURL: `${baseURL}/api/v1`,
|
||
headers: {
|
||
'Authorization': `Bearer ${apiToken}`,
|
||
'Content-Type': 'application/json',
|
||
},
|
||
});
|
||
}
|
||
|
||
async createFlow(provider: string, input: string): Promise<Flow> {
|
||
const query = `
|
||
mutation CreateFlow($provider: String!, $input: String!) {
|
||
createFlow(modelProvider: $provider, input: $input) {
|
||
id
|
||
title
|
||
status
|
||
createdAt
|
||
}
|
||
}
|
||
`;
|
||
|
||
const response = await this.client.post('/graphql', {
|
||
query,
|
||
variables: { provider, input },
|
||
});
|
||
|
||
return response.data.data.createFlow;
|
||
}
|
||
|
||
async getFlows(): Promise<Flow[]> {
|
||
const response = await this.client.get('/flows');
|
||
return response.data.flows;
|
||
}
|
||
|
||
async getFlow(flowId: string): Promise<Flow> {
|
||
const response = await this.client.get(`/flows/${flowId}`);
|
||
return response.data;
|
||
}
|
||
}
|
||
|
||
// Usage
|
||
const client = new PentAGIClient(
|
||
'https://your-pentagi-instance:8443',
|
||
'your_api_token_here'
|
||
);
|
||
|
||
// Create a new flow
|
||
const flow = await client.createFlow(
|
||
'openai',
|
||
'Perform penetration test on https://example.com'
|
||
);
|
||
console.log('Created flow:', flow);
|
||
|
||
// List all flows
|
||
const flows = await client.getFlows();
|
||
console.log(`Total flows: ${flows.length}`);
|
||
```
|
||
|
||
</details>
|
||
|
||
### 安全最佳实践
|
||
|
||
使用 API 令牌时：
|
||
|
||
- **切勿将令牌提交到版本控制** — 请使用环境变量或密钥管理服务
|
||
- **定期轮换令牌** — 设置合适的过期时间，并定期创建新令牌
|
||
- **为不同应用使用独立令牌** — 便于在需要时撤销访问权限
|
||
- **监控令牌使用情况** — 在 Settings 页面查看 API 令牌活动
|
||
- **撤销未使用的令牌** — 禁用或删除不再需要的令牌
|
||
- **仅使用 HTTPS** — 切勿通过未加密的连接发送 API 令牌
|
||
|
||
### 令牌管理
|
||
|
||
- **查看令牌**：在 Settings → API Tokens 中查看所有活跃令牌
|
||
- **编辑令牌**：更新令牌名称或撤销令牌
|
||
- **删除令牌**：永久删除令牌（此操作无法撤销）
|
||
- **令牌 ID**：每个令牌都有唯一的 ID，可复制以供参考
|
||
|
||
令牌列表显示：
|
||
- 令牌名称（如已提供）
|
||
- 令牌 ID（唯一标识符）
|
||
- 状态（active/revoked/expired）
|
||
- 创建日期
|
||
- 过期日期
|
||
|
||
### 自定义 LLM 提供商配置
|
||
|
||
将自定义 LLM 提供商与 `LLM_SERVER_*` 变量配合使用时，您可以微调请求中使用的推理格式。
|
||
|
||
> [!TIP]
|
||
> 对于生产级本地部署，建议使用 **vLLM** 配合 **Qwen3.5-27B-FP8** 以获得最佳性能。请参阅我们的[完整部署指南](examples/guides/vllm-qwen35-27b-fp8.md)，其中包含硬件要求、配置模板（[thinking mode](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml) 与 [non-thinking mode](examples/configs/vllm-qwen3.5-27b-fp8-no-think.provider.yml)），以及在 4× RTX 5090 GPU 上实现 13K TPS 提示词处理吞吐量的性能基准测试。
|
||
|
||
| Variable | Default | Description |
|
||
| ------------------------------- | ------- | --------------------------------------------------------------------------------------- |
|
||
| `LLM_SERVER_URL` | | 自定义 LLM API 端点的 Base URL |
|
||
| `LLM_SERVER_KEY` | | 自定义 LLM 提供商的 API 密钥 |
|
||
| `LLM_SERVER_MODEL` | | 默认使用的模型（可在提供商配置中覆盖） |
|
||
| `LLM_SERVER_CONFIG_PATH` | | Agent 专用模型的 YAML 配置文件路径 |
|
||
| `LLM_SERVER_PROVIDER` | | 模型名称的提供商名前缀（例如，LiteLLM proxy 使用 `openrouter`、`deepseek`） |
|
||
| `LLM_SERVER_LEGACY_REASONING` | `false` | 控制 API 请求中的推理（reasoning）格式 |
|
||
| `LLM_SERVER_PRESERVE_REASONING` | `false` | 在多轮对话中保留推理内容（部分提供商要求） |
|
||
|
||
`LLM_SERVER_PROVIDER` 设置在使用 **LiteLLM proxy** 时特别有用，该代理会为模型名称添加提供商前缀。例如，通过 LiteLLM 连接 Moonshot API 时，像 `kimi-2.5` 这样的模型会变成 `moonshot/kimi-2.5`。通过设置 `LLM_SERVER_PROVIDER=moonshot`，你可以使用同一份提供商配置文件，无需修改即可同时支持直接 API 访问和 LiteLLM proxy 访问。
|
||
|
||
`LLM_SERVER_LEGACY_REASONING` 设置影响推理参数如何发送至 LLM：
|
||
- `false`（默认）：使用现代格式，推理以结构化对象发送，并带有 `max_tokens` 参数
|
||
- `true`：使用旧版格式，采用基于字符串的 `reasoning_effort` 参数
|
||
|
||
在使用不同 LLM 提供商时，此设置很重要，因为各提供商可能在 API 请求中期望不同的推理格式。若在使用自定义提供商时遇到与推理相关的错误，请尝试更改此设置。
|
||
|
||
`LLM_SERVER_PRESERVE_REASONING` 设置控制是否在多轮对话中保留推理内容：
|
||
- `false`（默认）：对话历史中不保留推理内容
|
||
- `true`：保留推理内容并在后续 API 调用中发送
|
||
|
||
部分 LLM 提供商（例如 Moonshot）要求此设置；若多轮对话中未包含推理内容，可能返回类似 "thinking is enabled but reasoning_content is missing in assistant tool call message" 的错误。若你的提供商要求保留推理内容，请启用此设置。
|
||
|
||
### Ollama 提供商配置
|
||
|
||
PentAGI 支持 Ollama，可用于本地 LLM 推理（零成本、增强隐私）以及 Ollama Cloud（带免费额度的托管服务）。
|
||
|
||
#### 配置变量
|
||
|
||
| Variable | Default | Description |
|
||
| ----------------------------------- | ----------- | ----------------------------------------- |
|
||
| `OLLAMA_SERVER_URL` | | Ollama 服务器或 Ollama Cloud 的 URL |
|
||
| `OLLAMA_SERVER_API_KEY` | | Ollama Cloud 身份验证的 API 密钥 |
|
||
| `OLLAMA_SERVER_MODEL` | | 推理默认模型 |
|
||
| `OLLAMA_SERVER_CONFIG_PATH` | | 自定义 Agent 配置文件路径 |
|
||
| `OLLAMA_SERVER_PULL_MODELS_TIMEOUT` | `600` | 模型下载超时时间（秒） |
|
||
| `OLLAMA_SERVER_PULL_MODELS_ENABLED` | `false` | 启动时自动下载模型 |
|
||
| `OLLAMA_SERVER_LOAD_MODELS_ENABLED` | `false` | 向服务器查询可用模型 |
|
||
|
||
#### Ollama Cloud 配置
|
||
|
||
Ollama Cloud 提供托管推理服务，拥有慷慨的免费额度以及可扩展的付费方案。
|
||
|
||
**免费层级设置（单模型）**
|
||
|
||
```bash
|
||
# Free tier allows one model at a time
|
||
OLLAMA_SERVER_URL=https://ollama.com
|
||
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
|
||
OLLAMA_SERVER_MODEL=gpt-oss:120b # Example: OpenAI OSS 120B model
|
||
```
|
||
|
||
**付费层级设置（多模型与预构建配置）**
|
||
|
||
对于支持多个并发模型的付费层级，请使用预构建的 Ollama Cloud 配置：
|
||
|
||
```bash
|
||
# Using pre-built Ollama Cloud configuration (included in Docker image)
|
||
OLLAMA_SERVER_URL=https://ollama.com
|
||
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
|
||
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-cloud.provider.yml
|
||
```
|
||
|
||
预构建的 `ollama-cloud.provider.yml` 配置包含针对所有 Agent 类型的优化模型分配：
|
||
- **Simple/Assistant**：`nemotron-3-super:cloud` - 快速通用模型
|
||
- **Primary Agent**：`qwen3-coder-next:cloud` - 高努力模式的高级推理
|
||
- **Coder/Pentester**：`qwen3-coder-next:cloud` - 专用编码模型
|
||
- **Searcher**：`qwen3.5:397b-cloud` - 大上下文信息收集
|
||
- **Refiner/Refactor**：`glm-5:cloud` - 高质量文本精炼
|
||
- **Adviser/Enricher**：`minimax-m2.7:cloud` - 高效咨询任务
|
||
- **Installer**：`devstral-2:123b-cloud` - 安装与设置任务
|
||
|
||
**自定义配置（高级）**
|
||
|
||
要创建你自己的 Agent 配置，请从宿主机文件系统挂载自定义文件：
|
||
|
||
```bash
|
||
# Using custom provider configuration
|
||
OLLAMA_SERVER_URL=https://ollama.com
|
||
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
|
||
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama.provider.yml
|
||
|
||
# Mount custom configuration from host filesystem (in .env or docker-compose override)
|
||
PENTAGI_OLLAMA_SERVER_CONFIG_PATH=/path/on/host/my-ollama-config.yml
|
||
```
|
||
|
||
`PENTAGI_OLLAMA_SERVER_CONFIG_PATH` 环境变量将你的宿主机配置文件映射到容器内的 `/opt/pentagi/conf/ollama.provider.yml`。
|
||
|
||
**自定义配置示例**（`my-ollama-config.yml`）：
|
||
|
||
```yaml
|
||
primary_agent:
|
||
model: "qwen3-coder-next:cloud"
|
||
temperature: 1.0
|
||
top_p: 0.9
|
||
max_tokens: 32768
|
||
reasoning:
|
||
effort: high
|
||
|
||
coder:
|
||
model: "qwen3-coder:32b"
|
||
temperature: 1.0
|
||
max_tokens: 20480
|
||
```
|
||
|
||
#### 本地 Ollama 配置
|
||
|
||
对于自托管的 Ollama 实例：
|
||
|
||
```bash
|
||
# Basic local Ollama setup
|
||
OLLAMA_SERVER_URL=http://localhost:11434
|
||
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
|
||
|
||
# Production setup with auto-pull and model discovery
|
||
OLLAMA_SERVER_URL=http://ollama-server:11434
|
||
OLLAMA_SERVER_PULL_MODELS_ENABLED=true
|
||
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900
|
||
OLLAMA_SERVER_LOAD_MODELS_ENABLED=true
|
||
|
||
# Using pre-built configurations from Docker image
|
||
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
|
||
# or
|
||
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml
|
||
# or
|
||
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml
|
||
```
|
||
|
||
**性能注意事项：**
|
||
|
||
- **模型发现**（`OLLAMA_SERVER_LOAD_MODELS_ENABLED=true`）：查询 Ollama API 会增加 1-2 秒启动延迟
|
||
- **自动拉取**（`OLLAMA_SERVER_PULL_MODELS_ENABLED=true`）：首次启动可能需要数分钟下载模型
|
||
- **拉取超时**（`OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900`）：15 分钟（以秒为单位）
|
||
- **静态配置**：禁用上述两个标志并在配置文件中指定模型，可获得最快启动速度
|
||
|
||
#### 使用扩展上下文创建自定义 Ollama 模型
|
||
|
||
PentAGI 需要比默认 Ollama 配置更大的上下文窗口。你需要通过 Modelfile 创建带有更大 `num_ctx` 参数的自定义模型。虽然典型 Agent 工作流大约消耗 64K token，但 PentAGI 使用 110K 上下文大小，以留出安全余量并处理复杂的渗透测试场景。
|
||
|
||
**重要**：`num_ctx` 参数只能在通过 Modelfile 创建模型时设置——模型创建后无法更改，也无法在运行时覆盖。
|
||
|
||
##### 示例：带扩展上下文的 Qwen3 32B FP16
|
||
|
||
创建一个名为 `Modelfile_qwen3_32b_fp16_tc` 的 Modelfile：
|
||
|
||
```dockerfile
|
||
FROM qwen3:32b-fp16
|
||
PARAMETER num_ctx 110000
|
||
PARAMETER temperature 0.3
|
||
PARAMETER top_p 0.8
|
||
PARAMETER min_p 0.0
|
||
PARAMETER top_k 20
|
||
PARAMETER repeat_penalty 1.1
|
||
```
|
||
|
||
构建自定义模型：
|
||
|
||
```bash
|
||
ollama create qwen3:32b-fp16-tc -f Modelfile_qwen3_32b_fp16_tc
|
||
```
|
||
|
||
##### 示例：QwQ 32B FP16 扩展上下文
|
||
|
||
创建一个名为 `Modelfile_qwq_32b_fp16_tc` 的 Modelfile：
|
||
|
||
```dockerfile
|
||
FROM qwq:32b-fp16
|
||
PARAMETER num_ctx 110000
|
||
PARAMETER temperature 0.2
|
||
PARAMETER top_p 0.7
|
||
PARAMETER min_p 0.0
|
||
PARAMETER top_k 40
|
||
PARAMETER repeat_penalty 1.2
|
||
```
|
||
|
||
构建自定义模型：
|
||
|
||
```bash
|
||
ollama create qwq:32b-fp16-tc -f Modelfile_qwq_32b_fp16_tc
|
||
```
|
||
|
||
> **注意**：QwQ 32B FP16 模型推理大约需要 **71.3 GB VRAM**。在尝试使用该模型之前，请确保系统拥有足够的 GPU 显存。
|
||
|
||
这些自定义模型会在 Docker 镜像中 `/opt/pentagi/conf/` 路径下附带的预构建提供商配置文件（`ollama-qwen332b-fp16-tc.provider.yml` 和 `ollama-qwq32b-fp16-tc.provider.yml`）中被引用。
|
||
|
||
### OpenAI 提供商配置
|
||
|
||
PentAGI 与 OpenAI 全面的模型阵容集成，具备扩展思维链（chain-of-thought）的高级推理能力、增强工具集成的智能体（agentic）模型，以及面向安全工程的专业代码模型。
|
||
|
||
#### 配置变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
| -------------------- | --------------------------- | --------------------------- |
|
||
| `OPEN_AI_KEY` | | OpenAI 服务的 API 密钥 |
|
||
| `OPEN_AI_SERVER_URL` | `https://api.openai.com/v1` | OpenAI API 端点 |
|
||
|
||
#### 配置示例
|
||
|
||
```bash
|
||
# Basic OpenAI setup
|
||
OPEN_AI_KEY=your_openai_api_key
|
||
OPEN_AI_SERVER_URL=https://api.openai.com/v1
|
||
|
||
# Using with proxy for enhanced security
|
||
OPEN_AI_KEY=your_openai_api_key
|
||
PROXY_URL=http://your-proxy:8080
|
||
```
|
||
|
||
#### 支持的模型
|
||
|
||
PentAGI 支持 31 个具备工具调用、流式输出、推理模式和提示缓存（prompt caching）的 OpenAI 模型。标记为 `*` 的模型用于默认配置。
|
||
|
||
**GPT-5.2 系列 - 最新旗舰智能体模型（2025 年 12 月）**
|
||
|
||
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
|
||
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
|
||
| `gpt-5.2`* | ✅ | $1.75/$14.00/$0.18 | 最新旗舰模型，具备增强推理与工具集成，适用于自主安全研究 |
|
||
| `gpt-5.2-pro` | ✅ | $21.00/$168.00/$0.00 | 高级版本，具备卓越智能体编码能力，适用于关键任务安全研究与零日漏洞发现 |
|
||
| `gpt-5.2-codex` | ✅ | $1.75/$14.00/$0.18 | 最先进的代码专用模型，支持上下文压缩，具备强大网络安全能力 |
|
||
|
||
**GPT-5/5.1 系列 - 高级智能体模型**
|
||
|
||
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
|
||
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
|
||
| `gpt-5` | ✅ | $1.25/$10.00/$0.13 | 顶级智能体模型，具备高级推理能力，适用于自主安全研究与漏洞利用链开发 |
|
||
| `gpt-5.1` | ✅ | $1.25/$10.00/$0.13 | 增强型智能体模型，具备自适应推理，适用于均衡渗透测试与强大工具协同 |
|
||
| `gpt-5-pro` | ✅ | $15.00/$120.00/$0.00 | 高级版本，具备重大推理改进与更少幻觉，适用于关键安全操作 |
|
||
| `gpt-5-mini` | ✅ | $0.25/$2.00/$0.03 | 在速度与智能之间高效平衡，适用于自动化漏洞分析与漏洞利用生成 |
|
||
| `gpt-5-nano` | ✅ | $0.05/$0.40/$0.01 | 最快的高吞吐量扫描模型，适用于侦察与批量漏洞检测 |
|
||
|
||
**GPT-5/5.1 Codex 系列 - 代码专用模型**
|
||
|
||
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
|
||
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
|
||
| `gpt-5.1-codex-max` | ✅ | $1.25/$10.00/$0.13 | 面向复杂编码的增强推理，适用于已验证 CVE 发现与系统化漏洞利用开发 |
|
||
| `gpt-5.1-codex` | ✅ | $1.25/$10.00/$0.13 | 标准代码优化模型，具备强大推理能力，适用于漏洞利用生成与漏洞分析 |
|
||
| `gpt-5-codex` | ✅ | $1.25/$10.00/$0.13 | 基础代码专用模型，适用于漏洞扫描与基础漏洞利用生成 |
|
||
| `gpt-5.1-codex-mini` | ✅ | $0.25/$2.00/$0.03 | 紧凑高性能模型，容量提升 4 倍，适用于快速漏洞检测 |
|
||
| `codex-mini-latest` | ✅ | $1.50/$6.00/$0.38 | 最新紧凑代码模型，适用于自动化代码审查与基础漏洞分析 |
|
||
|
||
**GPT-4.1 系列 - 增强智能模型**
|
||
|
||
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
|
||
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
|
||
| `gpt-4.1` | ❌ | $2.00/$8.00/$0.50 | 增强旗舰模型，具备卓越函数调用能力，适用于复杂威胁分析与高级漏洞利用开发 |
|
||
| `gpt-4.1-mini`* | ❌ | $0.40/$1.60/$0.10 | 性能均衡且效率更高，适用于常规安全评估与自动化代码分析 |
|
||
| `gpt-4.1-nano` | ❌ | $0.10/$0.40/$0.03 | 超快轻量模型，适用于批量安全扫描、快速侦察与持续监控 |
|
||
|
||
**GPT-4o 系列 - 多模态旗舰模型**
|
||
|
||
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
|
||
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
|
||
| `gpt-4o` | ❌ | $2.50/$10.00/$1.25 | 多模态旗舰模型，具备视觉能力，适用于图像分析、Web UI 评估与多工具编排 |
|
||
| `gpt-4o-mini` | ❌ | $0.15/$0.60/$0.08 | 紧凑多模态模型，具备强大函数调用能力，适用于高频扫描与高性价比批量操作 |
|
||
|
||
**o 系列 - 高级推理模型**
|
||
|
||
| 模型 ID | 思考模式 | 价格（输入/输出/缓存） | 使用场景 |
|
||
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
|
||
| `o4-mini`* | ✅ | $1.10/$4.40/$0.28 | 下一代推理模型，速度更快，适用于系统化安全评估与系统化漏洞利用开发 |
|
||
| `o3`* | ✅ | $2.00/$8.00/$0.50 | 高级推理强力模型，适用于多阶段攻击链与深度漏洞分析 |
|
||
| `o3-mini` | ✅ | $1.10/$4.40/$0.55 | 紧凑推理模型，支持扩展思考，适用于分步攻击规划与逻辑化漏洞串联 |
|
||
| `o1` | ✅ | $15.00/$60.00/$7.50 | 顶级推理模型，具备最大深度，适用于高级渗透测试与新型漏洞利用研究 |
|
||
| `o3-pro` | ✅ | $20.00/$80.00/$0.00 | 最先进推理模型，比 o1-pro 便宜 80%，适用于零日研究与关键安全调查 |
|
||
| `o1-pro` | ✅ | $150.00/$600.00/$0.00 | 上一代高级推理模型，适用于详尽安全分析与关键任务挑战 |
|
||
|
||
**价格**：按每 100 万 token 计费。推理模型的输出定价包含思考 token。
|
||
|
||
> [!WARNING]
|
||
> **GPT-5* 模型 - 需要可信访问权限**
|
||
>
|
||
> 所有 GPT-5 系列模型（`gpt-5`、`gpt-5.1`、`gpt-5.2`、`gpt-5-pro`、`gpt-5.2-pro` 以及所有 Codex 变体）在 PentAGI 中运行**不稳定**，且在没有经过验证的访问权限时可能触发 OpenAI 的网络安全安全机制。
|
||
>
|
||
> **要可靠使用 GPT-5* 模型：**
|
||
> 1. **个人用户**：在 [chatgpt.com/cyber](https://chatgpt.com/cyber) 验证身份
|
||
> 2. **企业团队**：通过 OpenAI 代表申请可信访问权限
|
||
> 3. **安全研究人员**：申请 [网络安全资助计划（Cybersecurity Grant Program）](https://openai.com/form/cybersecurity-grant-program/)（包含 1000 万美元 API 额度）
|
||
>
|
||
> **无需验证的推荐替代方案：**
|
||
> - 推理任务使用 `o-series` 模型（o3、o4-mini、o1）
|
||
> - 通用智能与函数调用使用 `gpt-4.1` 系列
|
||
> - 所有 o 系列和 gpt-4.x 模型无需特殊访问权限即可稳定运行
|
||
|
||
**推理力度等级**：
|
||
- **High**：最大推理深度（refiner - o3，high effort）
|
||
- **Medium**：均衡推理（primary_agent、assistant、reflector - o4-mini/o3，medium effort）
|
||
- **Low**：高效定向推理（coder、installer、pentester - o3/o4-mini，low effort；adviser - gpt-5.2，low effort）
|
||
|
||
**核心特性**：
|
||
- **扩展推理（Extended Reasoning）**：o 系列模型配合思维链（chain-of-thought），用于复杂安全分析
|
||
- **智能体能力（Agentic Intelligence）**：GPT-5/5.1/5.2 系列，增强工具集成与自主能力
|
||
- **提示缓存（Prompt Caching）**：重复上下文可降低成本（约为输入价格的 10-50%）
|
||
- **代码专精**：专用 Codex 模型，用于漏洞发现与 exploit 开发
|
||
- **多模态支持**：GPT-4o 系列，用于基于视觉的安全评估
|
||
- **工具调用（Tool Calling）**：全系模型稳健函数调用，用于渗透测试工具编排
|
||
- **流式输出（Streaming）**：实时响应流，用于交互式工作流
|
||
- **成熟实绩**：行业领先模型，具备 CVE 发现与真实场景安全应用记录
|
||
|
||
### Anthropic 提供商配置
|
||
|
||
PentAGI 集成 Anthropic 的 Claude 模型，具备先进的扩展思考能力、卓越的安全机制，以及对复杂安全语境的深刻理解，并支持提示缓存。
|
||
|
||
#### 配置变量
|
||
|
||
| Variable | Default | Description |
|
||
| ---------------------- | ------------------------------ | ------------------------------ |
|
||
| `ANTHROPIC_API_KEY` | | Anthropic 服务 API 密钥 |
|
||
| `ANTHROPIC_SERVER_URL` | `https://api.anthropic.com/v1` | Anthropic API 端点 |
|
||
|
||
#### 配置示例
|
||
|
||
```bash
|
||
# Basic Anthropic setup
|
||
ANTHROPIC_API_KEY=your_anthropic_api_key
|
||
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1
|
||
|
||
# Using with proxy for secure environments
|
||
ANTHROPIC_API_KEY=your_anthropic_api_key
|
||
PROXY_URL=http://your-proxy:8080
|
||
```
|
||
|
||
> [!NOTE]
|
||
> **适用于 Claude 模型的 Google Vertex AI**
|
||
>
|
||
> PentAGI 目前在 `.env` 中尚未提供面向 Anthropic Claude 的专用 Google Vertex AI 配置路径。目前尚无独立的 Vertex AI API 密钥字段，现有 Anthropic 变量（`ANTHROPIC_API_KEY`、`ANTHROPIC_SERVER_URL`）指向 Anthropic 直连 API。Claude 的支持路由包括：
|
||
>
|
||
> - **Anthropic 直连 API**：`ANTHROPIC_API_KEY` 与 `ANTHROPIC_SERVER_URL`（见上文）。
|
||
> - **AWS Bedrock**：`BEDROCK_*` 相关变量（见 [AWS Bedrock 提供商配置](#aws-bedrock-provider-configuration)）。
|
||
>
|
||
> 若你当下需要使用 Vertex AI，最安全且受支持的变通方案是：通过 OpenAI 兼容代理或网关暴露 Vertex AI，将 Vertex AI 调用转换为 Chat Completions 格式，同时保留 PentAGI 所依赖的聊天与 tool-call 行为，然后通过 `LLM_SERVER_URL`、`LLM_SERVER_KEY` 与 `LLM_SERVER_MODEL` 将 Custom LLM 提供商指向该网关。此路径的可靠性取决于你所选网关。
|
||
|
||
#### 支持的模型
|
||
|
||
PentAGI 支持 10 款 Claude 模型，具备工具调用、流式输出、扩展思考、自适应思考与提示缓存。标有 `*` 的模型用于默认配置。
|
||
|
||
**Claude 4 系列 — 最新模型（2025-2026）**
|
||
|
||
| Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Use Case |
|
||
| ------------------------ | -------- | ------------ | ------------------------------ | ----------------------------------------------- |
|
||
| `claude-opus-4-6`* | ✅ | May 2025 | $5.00/$25.00/$0.50/$6.25 | 面向自主智能体与编码的最强模型。扩展 + 自适应思考，用于复杂 exploit 开发、多阶段攻击模拟 |
|
||
| `claude-sonnet-4-6`* | ✅ | Aug 2025 | $3.00/$15.00/$0.30/$3.75 | 速度与智能的最佳平衡，具备自适应思考。多阶段安全评估、智能漏洞分析、实时威胁狩猎 |
|
||
| `claude-haiku-4-5`* | ✅ | Oct 2025 | $1.00/$5.00/$0.10/$1.25 | 速度最快、接近前沿智能的模型。高频扫描、实时监控、批量自动化测试 |
|
||
|
||
**旧版模型 — 仍受支持**
|
||
|
||
| Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Use Case |
|
||
| ------------------------ | -------- | ------------ | ------------------------------ | ----------------------------------------------- |
|
||
| `claude-sonnet-4-5` | ✅ | Sep 2025 | $3.00/$15.00/$0.30/$3.75 | 顶尖推理能力（已被 4-6 取代）。复杂渗透测试、高级威胁分析 |
|
||
| `claude-opus-4-5` | ✅ | Nov 2025 | $5.00/$25.00/$0.50/$6.25 | 极致推理（已被 opus-4-6 取代）。关键安全研究、零日漏洞发现、红队行动 |
|
||
| `claude-opus-4-1` | ✅ | Aug 2025 | $15.00/$75.00/$1.50/$18.75 | 高级推理（已取代）。复杂渗透测试、精细威胁建模 |
|
||
| `claude-sonnet-4-0` | ✅ | May 2025 | $3.00/$15.00/$0.30/$3.75 | 高性能推理（已取代）。复杂威胁建模、多工具协同 |
|
||
| `claude-opus-4-0` | ✅ | May 2025 | $15.00/$75.00/$1.50/$18.75 | 第一代 Opus（已取代）。多步骤 exploit 开发、自主渗透测试工作流 |
|
||
|
||
**已弃用模型 — 请迁移至当前模型**
|
||
|
||
| Model ID | Thinking | Release Date | Price (Input/Output/Cache R/W) | Notes |
|
||
| ---------------------------- | -------- | ------------ | ------------------------------ | -------------------------------------------- |
|
||
| `claude-3-haiku-20240307` | ❌ | Mar 2024 | $0.25/$1.25/$0.03/$0.30 | 将于 2026 年 4 月 19 日停用。请迁移至 claude-haiku-4-5 |
|
||
|
||
**价格**：按每 100 万 token 计。缓存定价包含读与写成本。
|
||
|
||
**扩展思考配置**：
|
||
- **Max Tokens 4096**：Generator（claude-opus-4-6），用于复杂 exploit 开发的最大推理深度
|
||
- **Max Tokens 2048**：Coder（claude-sonnet-4-6），用于均衡的代码分析与漏洞研究
|
||
- **Max Tokens 1024**：Primary agent、assistant、refiner、adviser、reflector、searcher、installer、pentester，用于针对特定任务的聚焦推理
|
||
- **Extended Thinking**：所有 Claude 4.5+ 与 4.6 模型均支持可配置的扩展思考，用于深度推理任务
|
||
|
||
**核心特性**：
|
||
- **扩展思考（Extended Thinking）**：所有 Claude 4.5+ 与 4.6 模型，可配置思维链推理深度，用于复杂安全分析
|
||
- **自适应思考（Adaptive Thinking）**：Claude 4.6 系列（Opus/Sonnet）根据任务复杂度动态调整推理深度，以获得最佳性能
|
||
- **提示缓存（Prompt Caching）**：显著降低成本，读写分开计价（读为输入的 10%，写为输入的 125%）
|
||
- **扩展上下文窗口**：标准 200K token，Claude Opus/Sonnet 4.6 最高可达 1M token（beta），用于全面代码库分析
|
||
- **工具调用（Tool Calling）**：稳健的函数调用，精度出色，用于安全工具编排
|
||
- **流式输出（Streaming）**：实时响应流，用于交互式渗透测试工作流
|
||
- **安全优先设计**：内置安全机制，确保负责任的安全测试实践
|
||
- **多模态支持**：最新模型具备视觉能力，用于截图分析与 UI 安全评估
|
||
- **Constitutional AI**：先进安全训练，提供可靠且合乎伦理的安全指导
|
||
|
||
### Google AI（Gemini）提供商配置
|
||
|
||
PentAGI 通过 Google AI API 集成 Google 的 Gemini 模型，提供顶尖多模态推理能力，并支持扩展思考与上下文缓存。
|
||
|
||
#### 配置变量
|
||
|
||
| Variable | Default | Description |
|
||
| ------------------- | ------------------------------------------- | ------------------------------ |
|
||
| `GEMINI_API_KEY` | | Google AI 服务 API 密钥 |
|
||
| `GEMINI_SERVER_URL` | `https://generativelanguage.googleapis.com` | Google AI API 端点 |
|
||
|
||
#### 配置示例
|
||
|
||
```bash
|
||
# Basic Gemini setup
|
||
GEMINI_API_KEY=your_gemini_api_key
|
||
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com
|
||
|
||
# Using with proxy
|
||
GEMINI_API_KEY=your_gemini_api_key
|
||
PROXY_URL=http://your-proxy:8080
|
||
```
|
||
|
||
#### 支持的模型
|
||
|
||
PentAGI 支持 9 款 Gemini 模型，具备工具调用（tool calling）、流式输出（streaming）、思考模式（thinking modes）和上下文缓存（context caching）能力。标记为 `*` 的模型用于默认配置。
|
||
|
||
**Gemini 3.5 系列 - 最新稳定版 Flash（2026 年 5 月）**
|
||
|
||
| Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case |
|
||
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
|
||
| `gemini-3.5-flash`* | ✅ | 1M | $1.50/$9.00/$0.15 | 最智能的 Flash 模型，在智能体与编码任务上持续保持前沿性能，搜索与 grounding 能力出众 |
|
||
|
||
**Gemini 3.1 系列 - 稳定版 Flash-Lite + Pro 预览版（2026 年 2 月至 5 月）**
|
||
|
||
| Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case |
|
||
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
|
||
| `gemini-3.1-pro-preview`* | ✅ | 1M | $2.00/$12.00/$0.20 | 最新旗舰模型，思考能力更精炼、token 效率更高，针对软件工程与智能体工作流优化 |
|
||
| `gemini-3.1-pro-preview-customtools` | ✅ | 1M | $2.00/$12.00/$0.20 | 面向 bash 与自定义工具（view_file、search_code）优先级的自定义工具端点 |
|
||
| `gemini-3.1-flash-lite`* | ✅ | 1M | $0.25/$1.50/$0.025 | 最具成本效益的稳定多模态模型，面向高吞吐量智能体任务与低延迟应用提供前沿级性能 |
|
||
|
||
**Gemini 2.5 系列 - 高级思考模型（活跃至 2026 年 10 月 16 日）**
|
||
|
||
| Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
|
||
| `gemini-2.5-pro` | ✅ | 1M | $1.25/$10.00/$0.125 | 复杂编码与推理的顶尖选择，擅长精细化威胁建模 |
|
||
| `gemini-2.5-flash` | ✅ | 1M | $0.30/$2.50/$0.03 | 首款支持思考预算（thinking budgets）的混合推理模型，大规模评估场景下性价比最佳 |
|
||
| `gemini-2.5-flash-lite` | ✅ | 1M | $0.10/$0.40/$0.01 | 体量最小、成本最低，适合大规模使用与高吞吐量扫描 |
|
||
|
||
**Gemma 4 开源模型（Apache 2.0，免费层）**
|
||
|
||
| Model ID | Thinking | Context | Price (Input/Output/Cache) | Use Case |
|
||
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
|
||
| `gemma-4-31b-it` | ✅ | 256K | Free/Free/Free | 最大的 Gemma 4 开源稠密模型（约 31B 参数），多模态文本+图像，支持 140+ 种语言，适用于本地部署安全运营 |
|
||
| `gemma-4-26b-a4b-it` | ✅ | 256K | Free/Free/Free | MoE 架构（总参数约 26B / 激活参数约 3.8B），在消费级 GPU 上高效推理，适合本地高吞吐量扫描 |
|
||
|
||
**价格**：按每 100 万 token 计费（Standard Paid 层）。上下文窗口为输入 token 上限。
|
||
|
||
> [!NOTE]
|
||
> **Gemini 2.5 系列下线**
|
||
>
|
||
> `gemini-2.5-pro`、`gemini-2.5-flash` 和 `gemini-2.5-flash-lite` 将于 **2026 年 10 月 16 日** **下线**。建议迁移路径：
|
||
>
|
||
> - `gemini-2.5-pro` → `gemini-3.1-pro-preview`（相同 $2.00 输入定价层）
|
||
> - `gemini-2.5-flash` → `gemini-3.5-flash`（增强的前沿能力）
|
||
> - `gemini-2.5-flash-lite` → `gemini-3.1-flash-lite`（相同 $0.25 输入定价）
|
||
|
||
**默认模型分配（config.yml）**：
|
||
- **`gemini-3.1-pro-preview`** - `primary_agent`、`assistant`、`generator`、`refiner`、`adviser`、`coder`、`pentester`
|
||
- **`gemini-3.5-flash`** - `reflector`、`searcher`、`enricher`、`installer`
|
||
- **`gemini-3.1-flash-lite`** - `simple`、`simple_json`
|
||
|
||
**核心特性**：
|
||
- **扩展思考（Extended Thinking）**：面向复杂安全分析的逐步推理（所有 Gemini 3.x、2.5 系列及 Gemma 4 均支持可切换的思考模式）
|
||
- **上下文缓存（Context Caching）**：重复上下文可显著降低成本（多数模型为输入价格的 10%）
|
||
- **超长上下文（Ultra-Long Context）**：Gemini 对话模型支持 1M token，Gemma 4 开源模型支持 256K token
|
||
- **多模态支持（Multimodal Support）**：支持文本、图像、视频、音频和 PDF 处理，便于全面评估
|
||
- **工具调用（Tool Calling）**：通过函数调用无缝集成 20+ 款渗透测试工具
|
||
- **流式输出（Streaming）**：实时响应流，适用于交互式安全工作流
|
||
- **代码执行（Code Execution）**：内置代码执行，用于攻击性工具测试与漏洞利用验证
|
||
- **搜索 Grounding（Search Grounding）**：集成 Google Search，用于威胁情报与 CVE 研究
|
||
- **文件搜索（File Search）**：文档检索与 RAG 能力，支持基于知识的评估
|
||
- **批量 API（Batch API）**：非实时批量处理可节省 50% 成本
|
||
- **自定义工具端点（Custom Tools Endpoint）**：专用 `gemini-3.1-pro-preview-customtools` 路由，面向偏好已注册工具而非 bash 的工具密集型智能体工作流
|
||
|
||
**推理力度级别（Reasoning Effort Levels）**：
|
||
- **High**：最大思考深度，适用于复杂多步分析（generator）
|
||
- **Medium**：均衡推理，适用于通用智能体任务（primary_agent、assistant、refiner、adviser）
|
||
- **Low**：高效思考，适用于聚焦型任务（coder、installer、pentester）
|
||
|
||
### AWS Bedrock 提供商配置
|
||
|
||
PentAGI 集成 Amazon Bedrock，可访问来自 Anthropic、Amazon、Cohere、DeepSeek、OpenAI、Qwen、Mistral 和 Moonshot 等领先 AI 公司的 20+ 款基础模型。
|
||
|
||
#### 配置变量
|
||
|
||
| Variable | Default | Description |
|
||
| --------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
|
||
| `BEDROCK_REGION` | `us-east-1` | Bedrock 服务所在的 AWS 区域 |
|
||
| `BEDROCK_DEFAULT_AUTH` | `false` | 使用 AWS SDK 默认凭证链（环境变量、EC2 角色、~/.aws/credentials）——优先级最高 |
|
||
| `BEDROCK_BEARER_TOKEN` | | Bearer token 认证——优先级高于静态凭证 |
|
||
| `BEDROCK_ACCESS_KEY_ID` | | 静态凭证的 AWS 访问密钥 ID |
|
||
| `BEDROCK_SECRET_ACCESS_KEY` | | 静态凭证的 AWS 秘密访问密钥 |
|
||
| `BEDROCK_SESSION_TOKEN` | | 临时凭证的 AWS 会话令牌（可选，与静态凭证配合使用） |
|
||
| `BEDROCK_SERVER_URL` | | 自定义 Bedrock 端点（VPC 端点、本地测试） |
|
||
|
||
**认证优先级**：`BEDROCK_DEFAULT_AUTH` → `BEDROCK_BEARER_TOKEN` → `BEDROCK_ACCESS_KEY_ID`+`BEDROCK_SECRET_ACCESS_KEY`
|
||
|
||
#### 配置示例
|
||
|
||
```bash
|
||
# Recommended: Default AWS SDK authentication (EC2/ECS/Lambda roles)
|
||
BEDROCK_REGION=us-east-1
|
||
BEDROCK_DEFAULT_AUTH=true
|
||
|
||
# Bearer token authentication (AWS STS, custom auth)
|
||
BEDROCK_REGION=us-east-1
|
||
BEDROCK_BEARER_TOKEN=your_bearer_token
|
||
|
||
# Static credentials (development, testing)
|
||
BEDROCK_REGION=us-east-1
|
||
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
|
||
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
|
||
|
||
# With proxy and custom endpoint
|
||
BEDROCK_REGION=us-east-1
|
||
BEDROCK_DEFAULT_AUTH=true
|
||
BEDROCK_SERVER_URL=https://bedrock-runtime.us-east-1.vpce-xxx.amazonaws.com
|
||
PROXY_URL=http://your-proxy:8080
|
||
```
|
||
|
||
#### 支持的模型
|
||
|
||
PentAGI 支持 21 个具备工具调用、流式输出和多模态能力的 AWS Bedrock 模型。标有 `*` 的模型用于默认配置。
|
||
|
||
| Model ID | Provider | Thinking | Multimodal | Price (Input/Output) | Use Case |
|
||
| ------------------------------------------------ | --------------- | -------- | ---------- | -------------------- | --------------------------------------- |
|
||
| `us.amazon.nova-2-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.33/$2.75 | 自适应推理、高效思考 |
|
||
| `us.amazon.nova-premier-v1:0` | Amazon Nova | ❌ | ✅ | $2.50/$12.50 | 复杂推理、高级分析 |
|
||
| `us.amazon.nova-pro-v1:0` | Amazon Nova | ❌ | ✅ | $0.80/$3.20 | 准确度、速度与成本均衡 |
|
||
| `us.amazon.nova-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.06/$0.24 | 快速处理、高吞吐量操作 |
|
||
| `us.amazon.nova-micro-v1:0` | Amazon Nova | ❌ | ❌ | $0.035/$0.14 | 超低延迟、实时监控 |
|
||
| `us.anthropic.claude-opus-4-6-v1`* | Anthropic | ✅ | ✅ | $5.00/$25.00 | 世界级编码、企业级智能体 |
|
||
| `us.anthropic.claude-sonnet-4-6` | Anthropic | ✅ | ✅ | $3.00/$15.00 | 前沿智能、企业级规模 |
|
||
| `us.anthropic.claude-opus-4-5-20251101-v1:0` | Anthropic | ✅ | ✅ | $5.00/$25.00 | 多日软件开发 |
|
||
| `us.anthropic.claude-haiku-4-5-20251001-v1:0`* | Anthropic | ✅ | ✅ | $1.00/$5.00 | 接近前沿性能、高速响应 |
|
||
| `us.anthropic.claude-sonnet-4-5-20250929-v1:0`* | Anthropic | ✅ | ✅ | $3.00/$15.00 | 真实场景智能体、卓越编码能力 |
|
||
| `us.anthropic.claude-sonnet-4-20250514-v1:0` | Anthropic | ✅ | ✅ | $3.00/$15.00 | 性能均衡、可用于生产 |
|
||
| `us.anthropic.claude-3-5-haiku-20241022-v1:0` | Anthropic | ❌ | ❌ | $0.80/$4.00 | 最快模型、高性价比扫描 |
|
||
| `cohere.command-r-plus-v1:0` | Cohere | ❌ | ❌ | $3.00/$15.00 | 大规模操作、卓越 RAG |
|
||
| `deepseek.v3.2` | DeepSeek | ❌ | ❌ | $0.58/$1.68 | 长上下文推理、高效 |
|
||
| `openai.gpt-oss-120b-1:0`* | OpenAI (OSS) | ✅ | ❌ | $0.15/$0.60 | 强推理能力、科学分析 |
|
||
| `openai.gpt-oss-20b-1:0` | OpenAI (OSS) | ✅ | ❌ | $0.07/$0.30 | 高效编码、软件开发 |
|
||
| `qwen.qwen3-next-80b-a3b` | Qwen | ❌ | ❌ | $0.15/$1.20 | 超长上下文、旗舰级推理 |
|
||
| `qwen.qwen3-32b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | 推理均衡、研究场景 |
|
||
| `qwen.qwen3-coder-30b-a3b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | Vibe coding、自然语言优先 |
|
||
| `qwen.qwen3-coder-next` | Qwen | ❌ | ❌ | $0.45/$1.80 | 工具使用、函数调用优化 |
|
||
| `mistral.mistral-large-3-675b-instruct` | Mistral | ❌ | ✅ | $4.00/$12.00 | 高级多模态、长上下文 |
|
||
| `moonshotai.kimi-k2.5` | Moonshot | ❌ | ✅ | $0.60/$3.00 | 视觉、语言与代码一体化模型 |
|
||
|
||
**价格**：按每 100 万 token 计费。支持思考/推理的模型在推理阶段会产生额外计算成本。
|
||
|
||
#### 已测试但不兼容的模型
|
||
|
||
部分 AWS Bedrock 模型已完成测试，但由于技术限制**不受支持**：
|
||
|
||
| Model Family | Reason for Incompatibility |
|
||
| ------------------------- | ----------------------------------------------------------------------------------------- |
|
||
| **GLM (Z.AI)** | 工具调用格式与 Converse API 不兼容（期望字符串而非 JSON） |
|
||
| **AI21 Jamba** | 严格的速率限制（1-2 req/min）导致无法可靠测试及用于生产环境 |
|
||
| **Meta Llama 3.3/3.1** | 工具调用结果处理不稳定，会在多轮工作流中引发意外失败 |
|
||
| **Mistral Magistral** | 模型不支持工具调用 |
|
||
| **Moonshot K2-Thinking** | 带工具调用的流式输出行为不稳定，在生产环境中不可靠 |
|
||
| **Qwen3-VL** | 带工具调用的流式输出不稳定，多模态与工具组合会间歇性失败 |
|
||
|
||
> [!IMPORTANT]
|
||
> **速率限制与配额管理**
|
||
>
|
||
> Claude 模型的默认 AWS Bedrock 配额**极其严格**（新账户为 2-20 requests/minute）。用于生产级渗透测试时：
|
||
>
|
||
> 1. **申请提高配额**——通过 AWS Service Quotas 控制台为计划使用的模型提交配额提升申请
|
||
> 2. **使用 Amazon Nova 模型**——默认配额更高，性能出色
|
||
> 3. **启用预置吞吐量（provisioned throughput）**——用于稳定的高吞吐量测试
|
||
> 4. **监控用量**——达到配额上限时 AWS 会进行激进限流
|
||
>
|
||
> 若不提高配额，预计会出现频繁延迟和工作流中断。
|
||
|
||
> [!WARNING]
|
||
> **Converse API 要求**
|
||
>
|
||
> PentAGI 使用 Amazon Bedrock **Converse API** 实现统一模型访问。所有受支持的模型均需满足：
|
||
>
|
||
> - ✅ 支持 Converse/ConverseStream API
|
||
> - ✅ 支持工具使用（function calling），用于渗透测试工作流
|
||
> - ✅ 支持流式工具使用，以实现实时反馈
|
||
>
|
||
> 请在以下地址核实模型能力：[AWS Bedrock Model Features](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html)
|
||
|
||
**核心特性**：
|
||
- **自动提示缓存（Automatic Prompt Caching）**：重复上下文成本降低 40-70%（Claude 4.x 模型）
|
||
- **扩展思考（Extended Thinking）**：针对复杂安全分析的逐步推理（Claude、DeepSeek R1、OpenAI GPT）
|
||
- **多模态分析（Multimodal Analysis）**：处理截图、图表、视频以进行全面测试（Nova、Claude、Mistral、Kimi）
|
||
- **工具调用（Tool Calling）**：通过函数调用与 20+ 渗透测试工具无缝集成
|
||
- **流式输出（Streaming）**：实时响应流，适用于交互式安全评估工作流
|
||
|
||
### DeepSeek 提供商配置
|
||
|
||
PentAGI 集成 DeepSeek，以具有竞争力的价格提供先进 AI 模型访问，具备强推理能力、编码能力以及上下文缓存。
|
||
|
||
#### 配置变量
|
||
|
||
| Variable | Default Value | Description |
|
||
| --------------------- | -------------------------- | --------------------------------------------------- |
|
||
| `DEEPSEEK_API_KEY` | | 用于身份验证的 DeepSeek API 密钥 |
|
||
| `DEEPSEEK_SERVER_URL` | `https://api.deepseek.com` | DeepSeek API 端点 URL |
|
||
| `DEEPSEEK_PROVIDER` | | 用于 LiteLLM 集成的提供商前缀（可选） |
|
||
|
||
#### 配置示例
|
||
|
||
```bash
|
||
# Direct API usage
|
||
DEEPSEEK_API_KEY=your_deepseek_api_key
|
||
DEEPSEEK_SERVER_URL=https://api.deepseek.com
|
||
|
||
# With LiteLLM proxy
|
||
DEEPSEEK_API_KEY=your_litellm_key
|
||
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
|
||
DEEPSEEK_PROVIDER=deepseek # Adds prefix to model names (deepseek/deepseek-v4-flash) for LiteLLM
|
||
```
|
||
|
||
#### 支持的模型
|
||
|
||
PentAGI 支持 2 款 DeepSeek V4 模型，具备工具调用（tool calling）、流式输出（streaming）、混合思考/非思考模式以及上下文缓存（context caching）能力。两款模型默认启用思考模式，可通过 `extra_body` 切换为非思考模式。标有 `*` 的模型用于默认配置。
|
||
|
||
| Model ID | Thinking | Max Output | Context | Price (Input/Output/Cache) | Use Case |
|
||
| --------------------- | -------- | ---------- | ------- | -------------------------- | ---------------------------------------------------- |
|
||
| `deepseek-v4-flash`* | ✅ hybrid | 384K | 1M | $0.14/$0.28/$0.0028 | 实用型智能体、通用对话、快速工具调用 |
|
||
| `deepseek-v4-pro`* | ✅ hybrid | 384K | 1M | $1.74/$3.48/$0.0145 | 高级推理、复杂逻辑、安全分析 |
|
||
|
||
**价格**：按每 100 万 token 计费。缓存定价适用于从缓存提供的提示词 token（输入缓存命中，自 2026-04-26 起降至首发价格的 1/10）。两款模型均支持混合思考——默认启用 `thinking` 模式；传入 `extra_body.thinking.type: disabled` 可切换为非思考模式，以获得更快、更便宜的响应。
|
||
|
||
> **定价说明（deepseek-v4-pro）**：`deepseek-v4-pro` 的 75% 促销折扣已于 2026-05-31 15:59 UTC 正式结束。上表价格为促销结束后的标准定价。若你仍使用旧配置中的折扣价（$0.435/$0.87/$0.003625），请更新为当前费率，以便准确追踪成本。
|
||
|
||
> 旧版模型名称 `deepseek-chat` 和 `deepseek-reasoner` 已由 DeepSeek 计划于 2026-07-24 弃用。
|
||
> 引用这些旧名称的现有用户配置在此之前仍可正常使用；上表默认配置使用当前 V4 名称。`deepseek-chat` 映射至 `deepseek-v4-flash`
|
||
> 非思考模式；`deepseek-reasoner` 映射至 `deepseek-v4-flash` 思考模式。
|
||
|
||
**默认智能体配置**：
|
||
|
||
策略：优先将 `deepseek-v4-flash`（输入便宜 12 倍、输出便宜 12 倍）作为实用型/轻量级智能体的主力；将 `deepseek-v4-pro` 保留给复杂的多步推理任务。`installer` 智能体在 Flash 上运行并启用思考模式，因为环境搭建任务（shell 命令、配置编辑）通常不需要 Pro 级推理能力。在将更多智能体升级为 Pro 之前，请针对自身工作负载进行 A/B 测试。
|
||
|
||
| Agent Role | Default Model | Thinking | Reasoning Effort | Max Output | Temperature | Top P |
|
||
| ------------------------------------------- | -------------------- | -------- | ---------------- | ---------- | ----------- | ----- |
|
||
| Generator / Refiner | `deepseek-v4-pro` | Enabled | High | 32768 | (auto) | (auto) |
|
||
| Coder | `deepseek-v4-pro` | Enabled | High | 20480 | (auto) | (auto) |
|
||
| Primary Agent / Assistant / Pentester | `deepseek-v4-pro` | Enabled | High | 16384 | (auto) | (auto) |
|
||
| Adviser (mentor/planner) | `deepseek-v4-pro` | Enabled | High | 8192 | (auto) | (auto) |
|
||
| Installer | `deepseek-v4-flash` | Enabled | High | 12288 | (auto) | (auto) |
|
||
| Reflector / Searcher / Enricher | `deepseek-v4-flash` | Disabled | — | 4096 | 0.5 | 0.9 |
|
||
| Simple / Simple JSON | `deepseek-v4-flash` | Disabled | — | 2048 | 0.3 | 0.9 |
|
||
|
||
> **说明**：启用思考模式时，DeepSeek 会静默忽略 `temperature`、`top_p`、`presence_penalty` 和 `frequency_penalty`。当设置 `reasoning_effort` 时，langchaingo 客户端会自动将 `temperature`/`top_p` 置空，因此上表中显示为 "(auto)"。所有启用思考的智能体还会显式传入 `extra_body.thinking.type: enabled`，作为防御性编码，以应对未来提供商默认设置的变更。
|
||
|
||
**核心特性**：
|
||
- **混合思考模式（Hybrid Thinking Modes）**：通过 `extra_body.thinking.type` 在思考模式（深度推理）与非思考模式（快速响应）之间切换
|
||
- **自动提示词缓存（Automatic Prompt Caching）**：通过缓存命中定价（首发价格的 1/10）显著降低重复上下文的成本
|
||
- **扩展思考（Extended Thinking）**：面向复杂安全分析的强化学习 CoT（两款 V4 模型均支持）
|
||
- **强编码能力（Strong Coding）**：针对代码生成与漏洞利用开发进行优化
|
||
- **长上下文（Long Context）**：100 万 token 上下文窗口，最多 384K 输出 token
|
||
- **工具调用（Tool Calling）**：通过函数调用与 20+ 渗透测试工具无缝集成
|
||
- **流式输出（Streaming）**：为交互式工作流提供实时响应流
|
||
- **多语言（Multilingual）**：强大的中英文支持
|
||
- **其他特性（Additional Features）**：JSON 输出、Chat Prefix Completion（beta）、FIM/Fill-in-the-Middle Completion（仅非思考模式）
|
||
|
||
**并发限制**：`deepseek-v4-flash`：2500 个并发请求；`deepseek-v4-pro`：500 个并发请求。
|
||
|
||
**LiteLLM 集成**：设置 `DEEPSEEK_PROVIDER=deepseek` 可在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。直连 API 使用时请留空。
|
||
|
||
### GLM 提供商配置
|
||
|
||
PentAGI 集成智谱 AI（Z.AI）的 GLM，提供由清华大学开发、采用 MoE 架构、具备强推理与智能体能力的高级语言模型。
|
||
|
||
#### 配置变量
|
||
|
||
| Variable | Default Value | Description |
|
||
| ----------------- | ------------------------------- | ---------------------------------------------------------- |
|
||
| `GLM_API_KEY` | | 用于身份验证的 GLM API 密钥 |
|
||
| `GLM_SERVER_URL` | `https://api.z.ai/api/paas/v4` | GLM API 端点 URL（国际版） |
|
||
| `GLM_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） |
|
||
|
||
#### 配置示例
|
||
|
||
```bash
|
||
# Direct API usage (international endpoint)
|
||
GLM_API_KEY=your_glm_api_key
|
||
GLM_SERVER_URL=https://api.z.ai/api/paas/v4
|
||
|
||
# Alternative endpoints
|
||
GLM_SERVER_URL=https://open.bigmodel.cn/api/paas/v4 # China
|
||
GLM_SERVER_URL=https://api.z.ai/api/coding/paas/v4 # Coding-specific
|
||
|
||
# With LiteLLM proxy
|
||
GLM_API_KEY=your_litellm_key
|
||
GLM_SERVER_URL=http://litellm-proxy:4000
|
||
GLM_PROVIDER=zai # Adds prefix to model names (zai/glm-4) for LiteLLM
|
||
```
|
||
|
||
#### 支持的模型
|
||
|
||
PentAGI 支持 13 款 GLM 模型，具备工具调用、流式输出、混合思考模式以及提示词缓存能力。标有 `*` 的模型用于默认配置。思考模式通过 `extra_body.thinking.type`（"enabled"/"disabled"）控制；与 Kimi 不同，GLM 在两种模式下对 temperature 的限制都较为宽松。
|
||
|
||
**GLM-5.x 系列 - 最新一代（200K 上下文，128K 最大输出）**
|
||
|
||
| Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------------------------- |
|
||
| `glm-5.1`* | ✅ Hybrid | 200K | 128K | $1.40/$4.40/$0.26 | 最新旗舰：8 小时持续自主执行，对齐 Claude Opus 4.6（generator/refiner/adviser/coder/pentester 默认） |
|
||
| `glm-5` | ✅ Hybrid | 200K | 128K | $1.00/$3.20/$0.20 | 智能体工程（Agentic Engineering）基座，MoE 744B/40B active，Claude Opus 4.5 级编码能力 |
|
||
| `glm-5-turbo`* | ✅ Hybrid | 200K | 128K | $1.20/$4.00/$0.24 | OpenClaw 原生：针对工具调用、持久化任务、长链执行优化（primary_agent/assistant 默认） |
|
||
|
||
**GLM-4.7 系列 - 高级版，支持交错思考（Interleaved Thinking）**
|
||
|
||
| Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case |
|
||
| ----------------- | -------- | ------- | ---------- | -------------------------- | --------------------------------------------------- |
|
||
| `glm-4.7` | ✅ Hybrid | 200K | 128K | $0.60/$2.20/$0.11 | 增强编程能力，稳定的多步推理 |
|
||
| `glm-4.7-flashx` | ✅ Hybrid | 200K | 128K | $0.07/$0.40/$0.01 | 超低价且享有优先 GPU，但 RPM 限制较低（不适合高频使用） |
|
||
| `glm-4.7-flash` | ✅ Hybrid | 200K | 128K | Free/Free/Free | 免费约 30B SOTA 模型，1 个并发请求 |
|
||
|
||
**GLM-4.6 系列 - 均衡型，支持自动思考（Auto-Thinking）**
|
||
|
||
| Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case |
|
||
| --------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------- |
|
||
| `glm-4.6` | ✅ Auto | 200K | 128K | $0.60/$2.20/$0.11 | 均衡型、流式工具调用、省 token |
|
||
|
||
**GLM-4.5 系列 - 统一推理/编码/智能体**
|
||
|
||
| Model ID | Thinking | Context | Max Output | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------- | -------- | ------- | ---------- | -------------------------- | ------------------------------------------------- |
|
||
| `glm-4.5` | ✅ Auto | 128K | 96K | $0.60/$2.20/$0.11 | 统一型，MoE 355B/32B 激活参数 |
|
||
| `glm-4.5-x` | ✅ Auto | 128K | 96K | $2.20/$8.90/$0.45 | 超快高端版，最低延迟 |
|
||
| `glm-4.5-air`* | ✅ Auto | 128K | 96K | $0.20/$1.10/$0.03 | 高性价比 MoE 106B/12B（simple/simple_json/reflector/searcher/enricher/installer 默认） |
|
||
| `glm-4.5-airx` | ✅ Auto | 128K | 96K | $1.10/$4.50/$0.22 | 加速版 Air，优先 GPU |
|
||
| `glm-4.5-flash` | ✅ Auto | 128K | 96K | Free/Free/Free | 免费，支持推理/编码/智能体 |
|
||
|
||
**GLM-4 旧版 - 稠密架构（Dense Architecture）**
|
||
|
||
| Model ID | Thinking | Context | Max Output | Price (Input/Output) | Use Case |
|
||
| --------------------- | -------- | ------- | ---------- | -------------------- | --------------------------------------------- |
|
||
| `glm-4-32b-0414-128k` | ❌ | 128K | 16K | $0.10/$0.10 | 超低成本稠密 32B，无推理的解析任务 |
|
||
|
||
**价格**：按每 100 万 token 计费。缓存价格为提示词缓存命中价格；根据 Z.AI 促销，缓存存储目前免费。GLM-4-32B 不支持缓存。
|
||
|
||
**默认智能体配置**：
|
||
|
||
策略：关键推理使用 `glm-5.1`（最新旗舰，输入 $1.40），编排使用 `glm-5-turbo`（OpenClaw 原生、面向智能体优化），所有 utility/installer 智能体使用 `glm-4.5-air`（低价 MoE，支持混合思考且 RPM 稳定）。由于 RPM 限制较低，高频调用时易出现 429 错误，默认配置避免使用 `glm-4.7-flashx`。
|
||
|
||
| Agent Role | Default Model | Thinking | Temperature | Top P | Max Output |
|
||
| ----------------------------------- | ------------- | -------- | ----------- | ----- | ---------- |
|
||
| 生成器 / 精炼器 | `glm-5.1` | 启用 | 1.0 | 0.95 | 32768 |
|
||
| 编码器 | `glm-5.1` | 启用 | 1.0 | 0.95 | 20480 |
|
||
| 顾问 / 渗透测试 | `glm-5.1` | 启用 | 1.0 | 0.95 | 16384 |
|
||
| 主智能体 / 助手 | `glm-5-turbo` | 启用 | 1.0 | 0.95 | 16384 |
|
||
| 安装器 | `glm-4.5-air` | 启用 | 1.0 | 0.95 | 16384 |
|
||
| Simple / Reflector | `glm-4.5-air` | 禁用 | 0.6 | 0.9 | 8192 |
|
||
| 搜索器 / 增强器 / Simple JSON | `glm-4.5-air` | 禁用 | 0.6 | 0.9 | 4096 |
|
||
|
||
> **关于 temperature 的说明**：根据 Z.AI 文档，GLM 在思考/非思考模式下均接受 `1.0` 和 `0.6`。langchaingo 的 `IsReasoningModel` 会匹配 `glm-4.5*`/`glm-4.6*`/`glm-4.7*` 前缀，并在 `createChatRequest` 中强制将 temperature 覆盖为 1.0——这对 GLM 无害（与 Kimi 不同），但意味着这些模型在 YAML 中的 temperature 值仅供参考。`glm-5`/`glm-5.1`/`glm-5-turbo` 不会被匹配，因此显式设置的值会原样传递。
|
||
|
||
**思考模式**：
|
||
- **Hybrid（混合）**（GLM-5.x、GLM-4.7）：通过 `extra_body.thinking.type` 显式切换
|
||
- **Auto（自动）**（GLM-4.6、GLM-4.5 系列）：模型自动判断何时需要推理
|
||
- **Preserved Thinking（保留思考）**（Z.AI Coding 能力）：PentAGI 中所有启用思考的智能体也会传递 `extra_body.thinking.clear_thinking: false`，以便在对话中保留先前助手轮次的 `reasoning_content`。这在标准 API 端点（`/api/paas/v4`）上是必需的——在 Coding Plan 端点上默认启用。可提升多轮工具调用链中的推理连续性和缓存命中率。
|
||
- 所有启用思考的智能体也会出于防御性目的传递 `extra_body.tool_choice: auto`
|
||
|
||
**核心特性**：
|
||
- **长程任务（Long-Horizon Tasks）**：GLM-5.1 支持最长 8 小时的持续自主执行，适合复杂的多阶段智能体工作流
|
||
- **OpenClaw 原生编排**：GLM-5-Turbo 专门针对工具调用、指令遵循和长链执行进行了优化
|
||
- **提示词缓存（Prompt Caching）**：重复上下文可显著降低成本（表中已列出缓存输入价格）
|
||
- **超长上下文**：GLM-5.x/4.7/4.6 系列支持 200K token
|
||
- **MoE 架构**：高效 744B/40B 激活参数（GLM-5/5.1）、355B/32B（GLM-4.5）、106B/12B（GLM-4.5-Air）
|
||
- **工具调用（Tool Calling）**：通过 function calling 与 20+ 渗透测试工具无缝集成
|
||
- **流式输出（Streaming）**：实时流式输出，支持流式工具调用（GLM-4.6+）
|
||
- **多语言**：出色的中英文 NLP 能力
|
||
- **免费选项**：GLM-4.7-Flash 和 GLM-4.5-Flash 可用于原型开发与实验
|
||
|
||
**LiteLLM 集成**：将 `GLM_PROVIDER=zai` 设置为启用模型名前缀，以便在使用 LiteLLM 代理的默认 PentAGI 配置时生效。直接调用 API 时请留空。
|
||
|
||
### Kimi 提供商配置
|
||
|
||
PentAGI 集成 Moonshot AI 的 Kimi，提供具备多模态能力的超长上下文模型，非常适合分析大型代码库和文档。
|
||
|
||
#### 配置变量
|
||
|
||
| Variable | Default Value | Description |
|
||
| ------------------ | -----------------------------| --------------------------------------------------- |
|
||
| `KIMI_API_KEY` | | Kimi API 密钥，用于身份验证 |
|
||
| `KIMI_SERVER_URL` | `https://api.moonshot.ai/v1` | Kimi API 端点 URL（国际版） |
|
||
| `KIMI_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） |
|
||
|
||
#### 配置示例
|
||
|
||
```bash
|
||
# Direct API usage (international endpoint)
|
||
KIMI_API_KEY=your_kimi_api_key
|
||
KIMI_SERVER_URL=https://api.moonshot.ai/v1
|
||
|
||
# Alternative endpoint
|
||
KIMI_SERVER_URL=https://api.moonshot.cn/v1 # China
|
||
|
||
# With LiteLLM proxy
|
||
KIMI_API_KEY=your_litellm_key
|
||
KIMI_SERVER_URL=http://litellm-proxy:4000
|
||
KIMI_PROVIDER=moonshot # Adds prefix to model names (moonshot/kimi-k2.5) for LiteLLM
|
||
```
|
||
|
||
#### 支持的模型
|
||
|
||
PentAGI 支持 8 个具备工具调用、流式输出、混合思考模式及多模态能力（K2.x 支持文本/图像/视频）的 Kimi/Moonshot 模型。所有 `kimi-k2-*` 旧版模型（turbo-preview、0905-preview、0711-preview、thinking、thinking-turbo）已于 2026-05-25 被 Moonshot 弃用，未包含在内。标记为 `*` 的模型用于默认配置。
|
||
|
||
**Kimi K2.x 系列 - 多模态旗舰**
|
||
|
||
| Model ID | Thinking | Multimodal | Context | Price (Input Miss / Output / Cache Hit) | Use Case |
|
||
| ---------------- | -------- | ---------- | ------- | --------------------------------------- | ------------------------------------------------------- |
|
||
| `kimi-k2.6`* | ✅ hybrid | ✅ | 256K | $0.95 / $4.00 / $0.16 | 最新旗舰：原生多模态、更强代码能力、指令遵从性更佳（generator/refiner/adviser/coder/pentester 默认） |
|
||
| `kimi-k2.5`* | ✅ hybrid | ✅ | 256K | $0.60 / $3.00 / $0.10 | 上一代：输入价格低 36%，架构相同（primary/assistant/installer/utility 默认） |
|
||
|
||
**Moonshot V1 系列 - 生成模型（灵活参数）**
|
||
|
||
| Model ID | Thinking | Multimodal | Context | Price (Input / Output) | Use Case |
|
||
| ------------------- | -------- | ---------- | ------- | ---------------------- | ---------------------------------------------- |
|
||
| `moonshot-v1-8k` | ❌ | ❌ | 8K | $0.20 / $2.00 | 短文本生成，超低成本 |
|
||
| `moonshot-v1-32k` | ❌ | ❌ | 32K | $1.00 / $3.00 | 长文本生成 |
|
||
| `moonshot-v1-128k` | ❌ | ❌ | 128K | $2.00 / $5.00 | 超长上下文 |
|
||
|
||
**Moonshot V1 Vision 系列 - 图像理解**
|
||
|
||
| Model ID | Thinking | Multimodal | Context | Price (Input / Output) | Use Case |
|
||
| --------------------------------- | -------- | ---------- | ------- | ---------------------- | --------------------------------------- |
|
||
| `moonshot-v1-8k-vision-preview` | ❌ | ✅ | 8K | $0.20 / $2.00 | 视觉 + 短上下文 |
|
||
| `moonshot-v1-32k-vision-preview` | ❌ | ✅ | 32K | $1.00 / $3.00 | 视觉 + 中等上下文 |
|
||
| `moonshot-v1-128k-vision-preview` | ❌ | ✅ | 128K | $2.00 / $5.00 | 视觉 + 长上下文 |
|
||
|
||
**价格**：按每 100 万 token 计费。缓存定价适用于从自动上下文缓存（automatic context cache）提供的提示 token（仅 Kimi K2.x 模型支持缓存）。
|
||
|
||
> **重要 — Kimi K2.6/K2.5 参数约束**：API 对任何偏离将返回 `invalid_request_error`：
|
||
> - `temperature`：在 thinking 模式下 MUST 为 `1.0`，在非 thinking 模式下 MUST 为 `0.6`
|
||
> - `top_p`：MUST 为 `0.95`
|
||
> - `n`：MUST 为 `1`
|
||
> - `presence_penalty` 与 `frequency_penalty`：MUST 为 `0`（不可修改）
|
||
>
|
||
> Moonshot V1 模型使用标准 OpenAI 兼容参数，无此类约束。
|
||
|
||
**默认 Agent 配置**：
|
||
|
||
策略：优先选用 `kimi-k2.5` 作为高性价比主力模型（输入成本比 `kimi-k2.6` 低 36%）；将 `kimi-k2.6` 保留给关键推理任务。所有 `kimi-k2.x` agent 均配置 API 要求的固定参数（temp/top_p/n）及显式 `extra_body.thinking.type`。对于启用 thinking 的 agent，`extra_body.thinking.keep: "all"` 设置为在多轮工具调用链中保留历史 `reasoning_content`（若无此设置，Moonshot 将返回 "thinking is enabled but reasoning_content is missing"）。
|
||
|
||
| Agent Role | Default Model | Thinking | Temperature | Top P | Max Output |
|
||
| -------------------------------------------- | ------------- | -------- | ----------- | ----- | ---------- |
|
||
| Generator / Refiner | `kimi-k2.6` | Enabled (keep=all) | 1.0 | 0.95 | 32768 |
|
||
| Coder | `kimi-k2.6` | Enabled (keep=all) | 1.0 | 0.95 | 20480 |
|
||
| Pentester | `kimi-k2.6` | Enabled (keep=all) | 1.0 | 0.95 | 16384 |
|
||
| Adviser (mentor/planner) | `kimi-k2.6` | Enabled (keep=all) | 1.0 | 0.95 | 8192 |
|
||
| Primary Agent / Assistant | `kimi-k2.5` | Enabled (keep=all) | 1.0 | 0.95 | 16384 |
|
||
| Installer | `kimi-k2.5` | Enabled (keep=all) | 1.0 | 0.95 | 12288 |
|
||
| Reflector / Searcher / Enricher | `kimi-k2.5` | Disabled | 0.6 | 0.95 | 4096 |
|
||
| Simple / Simple JSON | `kimi-k2.5` | Disabled | 0.6 | 0.95 | 2048 |
|
||
|
||
**核心特性**：
|
||
- **超长上下文（Ultra-Long Context）**：最高 256K token（K2.x），适用于全面的代码库/文档分析
|
||
- **原生多模态（Native Multimodal）**：K2.6/K2.5 开箱即用地支持文本 + 图像 + 视频输入
|
||
- **混合思考（Hybrid Thinking）**：K2.6/K2.5 可通过 `extra_body.thinking.type` 在 thinking 与非 thinking 模式间切换
|
||
- **思考内容保留（Preserved Thinking）**（K2.6）：`thinking.keep: "all"` 在多轮对话中保留历史 `reasoning_content` — 多轮工具调用链所必需
|
||
- **自动上下文缓存（Automatic Context Caching）**：K2.x 模型缓存重复前缀（K2.6 约为未命中价格的 ~17%，K2.5 约为 ~17%）
|
||
- **工具调用（Tool Calling）**：K2.x 与 Moonshot V1 全面支持 function-calling
|
||
- **自我纠错（Self-Correction）**：K2.6 具备更强的指令遵循与自我纠错能力
|
||
- **多语言（Multilingual）**：强大的中文、英文及多语言支持
|
||
|
||
**Thinking + 工具调用的多轮对话**：PentAGI 的通用推理保留模式（`TextPartWithReasoning` + `WithPreserveReasoningContent`）自动确保按所需的 TextContent → ToolCall 顺序回传 `reasoning_content`，满足 Moonshot 对 "thinking is enabled but reasoning_content is missing in assistant tool call message" 的要求。
|
||
|
||
**LiteLLM 集成**：将 `KIMI_PROVIDER=moonshot` 设置为在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。直连 API 使用时留空即可。
|
||
|
||
### Qwen 提供商配置
|
||
|
||
PentAGI 集成阿里云百炼（DashScope）的 Qwen，提供具备推理能力与上下文缓存支持的强大多语言模型。
|
||
|
||
#### 配置变量
|
||
|
||
| Variable | Default Value | Description |
|
||
| ------------------ | ------------------------------------------------------ | --------------------------------------------------- |
|
||
| `QWEN_API_KEY` | | 用于身份验证的 Qwen API 密钥 |
|
||
| `QWEN_SERVER_URL` | `https://dashscope-us.aliyuncs.com/compatible-mode/v1` | Qwen API 端点 URL（国际版） |
|
||
| `QWEN_PROVIDER` | | LiteLLM 集成的提供商前缀（可选） |
|
||
|
||
#### 配置示例
|
||
|
||
```bash
|
||
# Direct API usage (Global/US endpoint)
|
||
QWEN_API_KEY=your_qwen_api_key
|
||
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1
|
||
|
||
# Alternative endpoints
|
||
QWEN_SERVER_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1 # International (Singapore)
|
||
QWEN_SERVER_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # Chinese Mainland (Beijing)
|
||
|
||
# With LiteLLM proxy
|
||
QWEN_API_KEY=your_litellm_key
|
||
QWEN_SERVER_URL=http://litellm-proxy:4000
|
||
QWEN_PROVIDER=dashscope # Adds prefix to model names (dashscope/qwen-plus) for LiteLLM
|
||
```
|
||
|
||
#### 支持的模型
|
||
|
||
PentAGI 支持 33 款为 agent 工作流精选的 Qwen 模型：文本推理、代码生成及视觉语言（浏览器截图）。所有模型均为非快照主别名，支持工具调用、流式输出、thinking 模式及上下文缓存。标记有 `*` 的模型用于默认配置。
|
||
|
||
**旗舰模型（顶级推理）**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3.7-max`* | ✅ | ✅ | ✅ | ✅ | $2.50/$7.50/$0.50 | 面向 agent 时代的新一代旗舰（generator/refiner/adviser 默认） |
|
||
| `qwen3.6-max-preview` | ✅ | ✅ | ✅ | ✅ | $1.30/$7.80/$0.13 | 预览版 Max，增强 vibe coding 与前端技能 |
|
||
| `qwen3-max` | ✅ | ✅ | ✅ | ✅ | $1.20/$6.00/$0.24 | 上一代旗舰，具备 agent 编程升级 |
|
||
| `qwen-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$4.00/$0.08 | 基于 Qwen3 的 Plus，可切换 thinking 模式 |
|
||
|
||
**均衡 Plus 模型（中档）**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3.6-plus`* | ✅ | ✅ | ✅ | ✅ | $0.50/$3.00/$0.05 | 原生 VL Plus，具备 agentic coding（primary/assistant/pentester 默认） |
|
||
| `qwen3.5-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$2.40/$0.04 | 上一代原生 VL，多模态能力强劲 |
|
||
|
||
**快速 Flash 模型（成本优化）**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3.6-flash` | ✅ | ✅ | ✅ | ✅ | $0.25/$1.50/$0.025 | 最新 Flash，显著增强 agentic 编码能力 |
|
||
| `qwen3.5-flash`* | ✅ | ✅ | ✅ | ✅ | $0.10/$0.40/$0.01 | 超快轻量（simple/reflector/searcher/enricher 默认） |
|
||
| `qwen-flash` | ✅ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | Qwen3 系列 Flash，1M 上下文，阶梯定价 |
|
||
|
||
**代码专用模型**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3-coder-plus`* | ❌ | ✅ | ✅ | ✅ | $1.00/$5.00/$0.20 | 强力编码智能体，支持自主编程（coder 默认） |
|
||
| `qwen3-coder-flash`* | ❌ | ✅ | ✅ | ✅ | $0.30/$1.50/$0.06 | 快速代码生成，多轮工具调用稳定（installer 默认） |
|
||
| `qwen3-coder-next` | ❌ | ✅ | ✅ | ✅ | $0.30/$1.50/— | 开源代码生成，同规模 SOTA |
|
||
|
||
**视觉语言模型（浏览器与截图分析）**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3-vl-plus` | ✅ | ✅ | ✅ | ✅ | $0.20/$1.60/$0.04 | 具备视觉智能体能力的 VL，超长视频理解 |
|
||
| `qwen3-vl-flash` | ✅ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | 小型 VL，2D/3D 定位，用于浏览器分流 |
|
||
| `qvq-max` | ✅ | ✅ | ✅ | ✅ | $1.20/$4.80/— | 视觉推理，支持思维链（chain-of-thought） |
|
||
|
||
**开源 Qwen3.6 系列**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3.6-27b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/— | 混合架构原生 VL，支持本地部署 |
|
||
| `qwen3.6-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$1.49/— | 高效 35B MoE（约 3B 活跃参数），适合持续监控 |
|
||
|
||
**开源 Qwen3.5 系列**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3.5-397b-a17b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/— | 最大 397B 参数（约 17B 活跃），卓越推理能力 |
|
||
| `qwen3.5-122b-a10b` | ✅ | ✅ | ✅ | ✅ | $0.40/$3.20/— | 大型 122B 参数（约 10B 活跃），强劲均衡 |
|
||
| `qwen3.5-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$2.00/— | 高效 35B MoE（约 3B 活跃参数），性价比高 |
|
||
| `qwen3.5-27b` | ✅ | ✅ | ✅ | ✅ | $0.30/$2.40/— | 中型 27B，混合线性注意力 + 稀疏 MoE |
|
||
|
||
**开源 Qwen3 Coder 系列**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ------------------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3-coder-480b-a35b-instruct` | ❌ | ✅ | ✅ | ✅ | $1.50/$7.50/— | 最大开源 Coder MoE（480B/约 35B 活跃） |
|
||
| `qwen3-coder-30b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.45/$2.25/— | 高效 30B MoE（约 3B 活跃参数），仓库级规模 |
|
||
|
||
**开源 Qwen3 Dense 与 MoE 系列**
|
||
|
||
| Model ID | Thinking | Intl | Global/US | China | Price (Input/Output/Cache) | Use Case |
|
||
| ------------------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ------------------------------------------------------- |
|
||
| `qwen3-next-80b-a3b-thinking` | ✅ | ✅ | ✅ | ✅ | $0.15/$1.20/— | 下一代 80B MoE（约 3B 活跃参数），仅思考模式 |
|
||
| `qwen3-next-80b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.15/$1.20/— | 下一代 80B MoE，指令遵循 |
|
||
| `qwen3-235b-a22b` | ✅ | ✅ | ✅ | ✅ | $0.70/$8.40/— | 双模式 235B MoE（约 22B 活跃） |
|
||
| `qwen3-32b` | ✅ | ✅ | ✅ | ✅ | $0.16/$0.64/— | 多功能 32B dense 双模式 |
|
||
| `qwen3-30b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.20/$2.40/— | 高效 30B MoE（约 3B 活跃参数） |
|
||
| `qwen3-14b` | ✅ | ✅ | ✅ | ✅ | $0.35/$4.20/— | 中型 14B dense，性能与成本均衡 |
|
||
| `qwen3-8b` | ✅ | ✅ | ✅ | ✅ | $0.18/$2.10/— | 紧凑 8B dense，高效 |
|
||
| `qwen3-4b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 轻量 4B dense，适合简单任务 |
|
||
| `qwen3-1.7b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 超紧凑 1.7B，基础检查 |
|
||
| `qwen3-0.6b` | ✅ | ✅ | ✅ | ✅ | $0.11/$1.26/— | 最小 0.6B，边缘监控 |
|
||
|
||
**价格**：按每 100 万 token 计费。缓存价格反映隐式缓存命中（如可用）；MoE/dense 开源模型不提供缓存定价。阶梯模型（Max/Plus）显示最低档价格（通常 ≤32k 或 ≤256k 输入）；更大上下文按阿里云定价收取更高费率。
|
||
|
||
**区域可用性**：
|
||
- **Intl**（国际）：新加坡区域（`dashscope-intl.aliyuncs.com`）
|
||
- **Global/US**：美国弗吉尼亚区域（`dashscope-us.aliyuncs.com`）
|
||
- **China**：中国大陆北京区域（`dashscope.aliyuncs.com`）
|
||
|
||
**默认智能体配置**：
|
||
| Agent Role | Default Model | Tier |
|
||
| ------------------------------------------------ | -------------------- | --------- |
|
||
| Generator / Refiner / Adviser（规划、导师） | `qwen3.7-max` | Flagship |
|
||
| Primary / Assistant / Pentester | `qwen3.6-plus` | Balanced |
|
||
| Coder（漏洞利用开发） | `qwen3-coder-plus` | Code+ |
|
||
| Installer（环境配置） | `qwen3-coder-flash` | Code Fast |
|
||
| Simple / Reflector / Searcher / Enricher | `qwen3.5-flash` | Fast |
|
||
|
||
**核心特性**：
|
||
- **以 Agent 为中心的设计**：Qwen3.7-Max 专为长周期自主执行与工具调用而打造
|
||
- **自动上下文缓存（Automatic Context Caching）**：通过隐式缓存，在重复上下文场景下可降低 30-50% 成本
|
||
- **扩展思考（Extended Thinking）**：面向复杂安全分析的链式思维推理（Qwen3.7/3.6/3.5/3-Max、QVQ-Max）
|
||
- **代码专精**：Qwen3-Coder 系列支持多轮工具交互与仓库级理解
|
||
- **视觉-语言（Vision-Language）**：Qwen3-VL 系列适用于浏览器截图分诊、2D/3D 定位、OCR 级分析
|
||
- **工具调用（Tool Calling）**：通过 function calling 与 20+ 款渗透测试工具无缝集成
|
||
- **流式输出（Streaming）**：为交互式工作流提供实时响应流
|
||
- **多语言（Multilingual）**：对中文、英文及多种语言有良好支持
|
||
- **开源变体（Open-Source Variants）**：提供 0.6B 至 480B 的 Dense 与 MoE 模型，适用于本地部署/气隙（air-gapped）环境
|
||
|
||
**LiteLLM 集成**：将 `QWEN_PROVIDER=dashscope` 设置为在使用默认 PentAGI 配置配合 LiteLLM 代理时启用模型名称前缀。若直接调用 API，请留空。
|
||
|
||
#### 其他集成方式
|
||
|
||
DashScope 完全兼容 OpenAI，因此 Qwen 也可通过标准 OpenAI 客户端为 PentAGI 的另外两个子系统提供能力。
|
||
|
||
**作为嵌入（embedding）提供方**（`text-embedding-v4`，参见 [Alibaba Cloud Model Studio 定价](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=prices)):
|
||
|
||
```bash
|
||
EMBEDDING_PROVIDER=openai
|
||
EMBEDDING_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1 # International (Singapore)
|
||
# EMBEDDING_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # Chinese Mainland
|
||
EMBEDDING_KEY=sk-*******
|
||
EMBEDDING_MODEL=text-embedding-v4
|
||
EMBEDDING_BATCH_SIZE= # optional, default applies
|
||
EMBEDDING_STRIP_NEW_LINES= # optional, default applies
|
||
```
|
||
|
||
> 注意：Global/US DashScope 端点（`dashscope-us.aliyuncs.com`）**不**提供 embedding API —— 请使用 International 或 China 端点以配置 `text-embedding-v4`。
|
||
|
||
**作为 OpenAI 类型的自定义 LLM 提供方**：无需使用专用的 `QWEN_*` 变量，可将任意 Qwen 对话模型通过 PentAGI 的自定义 OpenAI 兼容提供方接入：将 `OPENAI_SERVER_URL`（或自定义 provider 条目）指向 DashScope 的 `/compatible-mode/v1` 端点，并选择所需的 Qwen 模型名称。适用于你已通过单一 OpenAI 形态客户端统一管理全部模型流量（例如与 LiteLLM/OneAPI 代理共用）的场景。
|
||
|
||
## 高级配置
|
||
|
||
### Langfuse 集成
|
||
|
||
Langfuse 为监控与分析 AI Agent 运行提供高级能力。
|
||
|
||
1. 在现有的 `.env` 文件中配置 Langfuse 环境变量。
|
||
|
||
<details>
|
||
<summary>Langfuse 重要环境变量</summary>
|
||
|
||
### 数据库凭据
|
||
- `LANGFUSE_POSTGRES_USER` 与 `LANGFUSE_POSTGRES_PASSWORD` - Langfuse PostgreSQL 凭据
|
||
- `LANGFUSE_CLICKHOUSE_USER` 与 `LANGFUSE_CLICKHOUSE_PASSWORD` - ClickHouse 凭据
|
||
- `LANGFUSE_REDIS_AUTH` - Redis 密码
|
||
|
||
### 加密与安全密钥
|
||
- `LANGFUSE_SALT` - Langfuse Web UI 中用于哈希的盐值
|
||
- `LANGFUSE_ENCRYPTION_KEY` - 加密密钥（32 字节十六进制）
|
||
- `LANGFUSE_NEXTAUTH_SECRET` - NextAuth 密钥
|
||
|
||
### 管理员凭据
|
||
- `LANGFUSE_INIT_USER_EMAIL` - 管理员邮箱
|
||
- `LANGFUSE_INIT_USER_PASSWORD` - 管理员密码
|
||
- `LANGFUSE_INIT_USER_NAME` - 管理员用户名
|
||
|
||
### API 密钥与令牌
|
||
- `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` - 项目公钥（PentAGI 侧也会使用）
|
||
- `LANGFUSE_INIT_PROJECT_SECRET_KEY` - 项目私钥（PentAGI 侧也会使用）
|
||
|
||
### S3 存储
|
||
- `LANGFUSE_S3_ACCESS_KEY_ID` - S3 访问密钥 ID
|
||
- `LANGFUSE_S3_SECRET_ACCESS_KEY` - S3 秘密访问密钥
|
||
|
||
</details>
|
||
|
||
2. 在 `.env` 文件中为 PentAGI 服务启用 Langfuse 集成。
|
||
|
||
```bash
|
||
LANGFUSE_BASE_URL=http://langfuse-web:3000
|
||
LANGFUSE_PROJECT_ID= # default: value from ${LANGFUSE_INIT_PROJECT_ID}
|
||
LANGFUSE_PUBLIC_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY}
|
||
LANGFUSE_SECRET_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_SECRET_KEY}
|
||
```
|
||
|
||
3. 启动 Langfuse 栈：
|
||
|
||
```bash
|
||
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-langfuse.yml
|
||
docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d
|
||
```
|
||
|
||
访问 [localhost:4000](http://localhost:4000) 以使用 `.env` 文件中的凭据登录 Langfuse Web UI：
|
||
|
||
- `LANGFUSE_INIT_USER_EMAIL` - 管理员邮箱
|
||
- `LANGFUSE_INIT_USER_PASSWORD` - 管理员密码
|
||
|
||
### 监控与可观测性
|
||
|
||
如需详细跟踪系统运行，可集成监控工具。
|
||
|
||
1. 在 `.env` 文件中为 PentAGI 启用 OpenTelemetry 及全部可观测性服务集成。
|
||
|
||
```bash
|
||
OTEL_HOST=otelcol:8148
|
||
```
|
||
|
||
2. 启动可观测性栈：
|
||
|
||
```bash
|
||
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-observability.yml
|
||
docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d
|
||
```
|
||
|
||
访问 [localhost:3000](http://localhost:3000) 以打开 Grafana Web UI。
|
||
|
||
> [!NOTE]
|
||
> 若要将可观测性栈与 Langfuse 一起使用，需在 `.env` 文件中启用集成，将 `LANGFUSE_OTEL_EXPORTER_OTLP_ENDPOINT` 设置为 `http://otelcol:4318`。
|
||
>
|
||
> 要同时运行所有可用栈（Langfuse、Graphiti 与 Observability）：
|
||
>
|
||
> ```bash
|
||
> docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml up -d
|
||
> ```
|
||
>
|
||
> 你也可以在 shell 中为这些命令注册别名以便更快执行：
|
||
>
|
||
> ```bash
|
||
> alias pentagi="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml"
|
||
> alias pentagi-up="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml up -d"
|
||
> alias pentagi-down="docker compose -f docker-compose.yml -f docker-compose-langfuse.yml -f docker-compose-graphiti.yml -f docker-compose-observability.yml down"
|
||
> ```
|
||
|
||
### 知识图谱集成（Graphiti）
|
||
|
||
> [!IMPORTANT]
|
||
> Graphiti 集成目前为 **beta** 功能，存在明显的提供方限制。在生产环境启用前，请参阅下文 [当前限制](#current-limitations)。
|
||
|
||
PentAGI 与 [Graphiti](https://github.com/vxcontrol/pentagi-graphiti), 集成 —— 这是一个由 Neo4j 驱动的时序知识图谱系统，可为 AI Agent 运行提供高级语义理解与关系追踪。vxcontrol 分支提供了针对渗透测试场景的自定义实体与边类型。
|
||
|
||
#### 什么是 Graphiti？
|
||
|
||
Graphiti 会自动从 Agent 交互中提取并存储结构化知识，构建实体、关系与时序上下文的图谱。由此可实现：
|
||
|
||
- **语义记忆（Semantic Memory）**：存储并回忆工具、目标、漏洞与技术之间的关联
|
||
- **上下文理解（Contextual Understanding）**：追踪不同渗透测试操作如何随时间相互关联
|
||
- **知识复用（Knowledge Reuse）**：从过往渗透测试中学习，并将洞察应用于新评估
|
||
- **高级查询（Advanced Querying）**：搜索复杂模式，例如「哪些工具对类似目标有效？」
|
||
|
||
#### 启用 Graphiti
|
||
|
||
Graphiti 知识图谱为**可选**功能，默认关闭。启用步骤：
|
||
|
||
1. 在 `.env` 文件中配置 Graphiti 环境变量：
|
||
|
||
```bash
|
||
## Graphiti knowledge graph settings
|
||
GRAPHITI_ENABLED=true
|
||
GRAPHITI_TIMEOUT=30
|
||
GRAPHITI_URL=http://graphiti:8000
|
||
GRAPHITI_MODEL_NAME=gpt-5-mini
|
||
|
||
# Neo4j settings (used by Graphiti stack)
|
||
NEO4J_USER=neo4j
|
||
NEO4J_DATABASE=neo4j
|
||
NEO4J_PASSWORD=devpassword
|
||
NEO4J_URI=bolt://neo4j:7687
|
||
|
||
# OpenAI API key (required by Graphiti for entity extraction)
|
||
OPEN_AI_KEY=your_openai_api_key
|
||
```
|
||
|
||
2. 与 PentAGI 主服务一并启动 Graphiti 栈：
|
||
|
||
```bash
|
||
# Download the Graphiti compose file if needed
|
||
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml
|
||
|
||
# Start PentAGI with Graphiti
|
||
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d
|
||
```
|
||
|
||
3. 验证 Graphiti 是否正在运行：
|
||
|
||
```bash
|
||
# Check service health
|
||
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml ps graphiti neo4j
|
||
|
||
# View Graphiti logs
|
||
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f graphiti
|
||
|
||
# Access Neo4j Browser (optional)
|
||
# Visit http://localhost:7474 and login with NEO4J_USER/NEO4J_PASSWORD
|
||
|
||
# Access Graphiti API (optional, for debugging)
|
||
# Visit http://localhost:8000/docs for Swagger API documentation
|
||
```
|
||
|
||
> [!NOTE]
|
||
> Graphiti 服务在 `docker-compose-graphiti.yml` 中定义为独立堆栈。你必须同时运行这两个 compose 文件才能启用知识图谱功能。默认使用预构建的 Docker 镜像 `vxcontrol/graphiti:latest`。
|
||
|
||
#### 存储内容
|
||
|
||
启用后，PentAGI 会自动捕获：
|
||
|
||
- **Agent 响应（Agent Responses）**：所有 agent 的推理、分析与决策
|
||
- **工具执行（Tool Executions）**：已执行的命令、使用的工具及其结果
|
||
- **上下文信息（Context Information）**：Flow、任务与子任务的层级结构
|
||
|
||
#### 当前限制
|
||
|
||
Graphiti 集成目前为 beta 功能。在生产环境中启用前，运维人员应针对以下约束做好规划：
|
||
|
||
- **仅支持 OpenAI 兼容 LLM。** 捆绑的 `vxcontrol/graphiti` 镜像针对通过 PentAGI 的 `.env` 变量 `OPEN_AI_KEY` 与 `OPEN_AI_SERVER_URL`（默认 `https://api.openai.com/v1`）配置的单一 OpenAI 兼容端点进行认证。`docker-compose-graphiti.yml` 会将其映射到容器内的 `OPENAI_API_KEY` 与 `OPENAI_BASE_URL`，因此运维人员无需直接设置容器变量。PentAGI 中在其他位置为 Anthropic、Google AI（Gemini）、AWS Bedrock、DeepSeek、GLM、Kimi 或 Qwen 配置的提供商凭据**不会**被 Graphiti 用于实体抽取。若你的部署无法访问 OpenAI 兼容端点，请保持 `GRAPHITI_ENABLED=false`。
|
||
- **每个部署固定单一模型。** Graphiti 对所有抽取使用同一模型名称（`GRAPHITI_MODEL_NAME`，默认 `gpt-5-mini`）。无法按 agent 或 flow 选择模型。
|
||
- **独立计费。** 即使 flow 使用非 OpenAI 提供商运行，Graphiti 仍会在所配置的 OpenAI 兼容端点上产生费用。
|
||
- **尚无应用内图谱浏览器。** 浏览已捕获的图谱需依赖 `http://localhost:7474` 上的 Neo4j Browser 与 `http://localhost:8000/docs` 上的 Graphiti Swagger UI。目前 PentAGI 没有面向图谱的 UI 界面。
|
||
|
||
当 `GRAPHITI_ENABLED=false` 时，PentAGI 会继续使用其主内存与向量存储运行；仅跳过额外的知识图谱功能。
|
||
|
||
### GitHub 与 Google OAuth 集成
|
||
|
||
与 GitHub 和 Google 的 OAuth 集成允许用户使用这些平台上的现有账户进行身份验证。这带来多项好处：
|
||
|
||
- 简化登录流程，无需创建独立凭据
|
||
- 通过可信身份提供商增强安全性
|
||
- 可访问 GitHub/Google 账户中的用户资料信息
|
||
- 与现有开发工作流无缝集成
|
||
|
||
PentAGI 使用 `PUBLIC_URL` 作为 OAuth 重定向的公开源站/基础 URL。在默认部署中，GitHub 与 Google 回调均由以下端点处理：
|
||
|
||
```text
|
||
${PUBLIC_URL}/api/v1/auth/login-callback
|
||
```
|
||
|
||
GitHub OAuth：
|
||
|
||
1. 在你的 GitHub 账户中创建新的 OAuth App。
|
||
2. 将 **Homepage URL** 设置为你的 `PUBLIC_URL`。
|
||
3. 将 **Authorization callback URL** 设置为 `${PUBLIC_URL}/api/v1/auth/login-callback`。
|
||
4. 将客户端凭据添加到你的 `.env` 文件：
|
||
|
||
```bash
|
||
PUBLIC_URL=https://pentagi.example.com
|
||
OAUTH_GITHUB_CLIENT_ID=your_github_client_id
|
||
OAUTH_GITHUB_CLIENT_SECRET=your_github_client_secret
|
||
```
|
||
|
||
Google OAuth：
|
||
|
||
1. 在你的 Google Cloud 项目中创建 OAuth 凭据。
|
||
2. 使用相同的回调端点：`${PUBLIC_URL}/api/v1/auth/login-callback`。
|
||
3. 将客户端凭据添加到你的 `.env` 文件：
|
||
|
||
```bash
|
||
PUBLIC_URL=https://pentagi.example.com
|
||
OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
|
||
OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
|
||
```
|
||
|
||
请确保 `PUBLIC_URL` 与 PentAGI 实例对外可访问的 HTTPS 地址一致，且本身不包含回调路径。若在 OAuth 提供商处配置的 URL 与 PentAGI 生成的回调不完全匹配，提供商将因 redirect URI 不匹配而拒绝登录尝试。
|
||
|
||
### Docker 镜像配置
|
||
|
||
PentAGI 允许你配置用于执行各类任务的 Docker 镜像选择。系统会根据任务类型自动选择最合适的镜像，但你可以通过指定首选镜像来约束这一选择：
|
||
|
||
| Variable | Default | Description |
|
||
| ---------------------------------- | ---------------------- | ----------------------------------------------------------- |
|
||
| `PENTAGI_IMAGE` | `vxcontrol/pentagi:latest` | 主 PentAGI 应用服务使用的 Docker 镜像 |
|
||
| `DOCKER_DEFAULT_IMAGE` | `debian:latest` | 一般任务与模糊场景的默认 Docker 镜像 |
|
||
| `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` | `vxcontrol/kali-linux` | 安全/渗透测试任务的默认 Docker 镜像 |
|
||
|
||
`PENTAGI_IMAGE` 会更改 `docker-compose.yml` 中主 `pentagi` 服务所使用的镜像。`DOCKER_DEFAULT_IMAGE` 与 `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` 变量仅影响 PentAGI 内部任务执行时的自动 worker 镜像选择。它们不会改写 Compose 堆栈的其余部分，因此 `pgvector`、`scraper` 以及可选的 `graphiti` 堆栈等服务仍使用 compose 文件中定义的镜像引用。
|
||
|
||
当设置 `DOCKER_DEFAULT_IMAGE` 与 `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` 时，AI agent 将仅限于你指定的镜像选择。这在以下场景尤其有用：
|
||
|
||
- **安全强制（Security Enforcement）**：限制仅使用已验证且受信任的镜像
|
||
- **环境标准化（Environment Standardization）**：在所有操作中使用企业或定制镜像
|
||
- **性能优化（Performance Optimization）**：使用已预装必要工具的镜像
|
||
|
||
配置示例：
|
||
|
||
```bash
|
||
# Using a custom PentAGI application image
|
||
PENTAGI_IMAGE=registry.example.com/security/pentagi:latest
|
||
|
||
# Using a custom image for general tasks
|
||
DOCKER_DEFAULT_IMAGE=mycompany/custom-debian:latest
|
||
|
||
# Using a specialized image for penetration testing
|
||
DOCKER_DEFAULT_IMAGE_FOR_PENTEST=mycompany/pentest-tools:v2.0
|
||
```
|
||
|
||
> [!NOTE]
|
||
> 若用户在任务中显式指定了特定 Docker 镜像，系统将尝试使用该确切镜像，忽略这些设置。这些变量仅影响系统的自动镜像选择流程。
|
||
|
||
有关使用自定义渗透测试镜像进行高级 OpenVAS/GVM 实验，请参阅 [OpenVAS via a Custom Pentest Image](examples/guides/openvas-custom-image.md)。
|
||
|
||
#### 受限网络、Docker 镜像源与代理
|
||
|
||
若你的环境无法直接访问 Docker Hub（`docker.io`），仅修改 PentAGI 环境变量通常不足以解决镜像下载失败。PentAGI 仍依赖 Docker 自身的 registry 访问来管理 Compose 服务，安装程序的网络检查也会验证 Docker Hub 可达性。
|
||
|
||
对于受限网络：
|
||
|
||
1. 确认主机能够解析并访问 `docker.io`。
|
||
2. 若环境需要出站代理以访问 PentAGI 或安装程序的 HTTP 流量，请设置 `PROXY_URL` 环境变量。若要通过代理拉取 Docker 镜像，请单独配置 Docker 守护进程或 Docker Desktop 代理——Docker 不会使用 PentAGI 的 `PROXY_URL` 进行 registry 访问。
|
||
3. 若 Docker Hub 被封锁或严重限流，请在运行安装程序或 `docker compose up` 之前配置组织批准的 registry 镜像或 registry 代理。
|
||
4. 修改守护进程配置后重启 Docker，然后重新运行安装程序检查或 Compose 启动。
|
||
|
||
Docker 守护进程镜像源配置示例：
|
||
|
||
```json
|
||
{
|
||
"registry-mirrors": ["https://mirror.example.com"]
|
||
}
|
||
```
|
||
|
||
在 Linux 上，通常可在 `/etc/docker/daemon.json` 中进行配置。在 Docker Desktop 上，请使用等效的 Docker Engine 或代理设置。Docker Hub 镜像可覆盖 Docker Hub 托管的镜像（例如 `vxcontrol/*`），但主 Compose 栈已包含 `quay.io/prometheuscommunity/postgres-exporter`，可选的可观测性栈则包含 `gcr.io/cadvisor/cadvisor`。这些 registry 仍需要直连访问，或单独获批的代理/镜像路径。
|
||
|
||
请参阅官方 Docker 文档：[registry mirrors](https://docs.docker.com/docker-hub/image-library/mirror/) 和 [daemon proxy configuration](https://docs.docker.com/engine/daemon/proxy/).
|
||
|
||
## 开发
|
||
|
||
### 开发环境要求
|
||
|
||
- golang
|
||
- nodejs
|
||
- docker
|
||
- postgres
|
||
- commitlint
|
||
|
||
### 环境配置
|
||
|
||
#### 后端配置
|
||
|
||
运行一次 `cd backend && go mod download` 以安装所需软件包。
|
||
|
||
生成 swagger 文件需要运行
|
||
|
||
```bash
|
||
swag init -g ../../pkg/server/router.go -o pkg/server/docs/ --parseDependency --parseInternal --parseDepth 2 -d cmd/pentagi
|
||
```
|
||
|
||
然后通过以下方式安装 `swag` 软件包
|
||
|
||
```bash
|
||
go install github.com/swaggo/swag/cmd/swag@v1.8.7
|
||
```
|
||
|
||
生成 graphql resolver 文件需要运行
|
||
|
||
```bash
|
||
go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml
|
||
```
|
||
|
||
之后可在 `pkg/graph` 文件夹中查看生成的文件。
|
||
|
||
根据 sqlc 配置生成 ORM 方法（database 包）
|
||
|
||
```bash
|
||
docker run --rm -v $(pwd):/src -w /src --network pentagi-network -e DATABASE_URL="{URL}" sqlc/sqlc:1.27.0 generate -f sqlc/sqlc.yml
|
||
```
|
||
|
||
根据 OpenAPI 规范生成 Langfuse SDK
|
||
|
||
```bash
|
||
fern generate --local
|
||
```
|
||
|
||
并安装 fern-cli
|
||
|
||
```bash
|
||
pnpm add -g fern-api
|
||
```
|
||
|
||
#### 测试
|
||
|
||
运行测试：`cd backend && go test -v ./...`
|
||
|
||
#### 前端配置
|
||
|
||
运行一次 `cd frontend && pnpm install` 以安装所需软件包。
|
||
|
||
生成 graphql 文件需要运行 `pnpm run graphql:generate`，它使用 `graphql-codegen.ts` 文件。
|
||
|
||
请确保已全局安装 `graphql-codegen`：
|
||
|
||
```bash
|
||
pnpm add -g graphql-codegen
|
||
```
|
||
|
||
之后可以运行：
|
||
* `pnpm run prettier` —— 检查代码格式是否正确
|
||
* `pnpm run prettier:fix` —— 修复格式问题
|
||
* `pnpm run lint` —— 检查代码 lint 是否正确
|
||
* `pnpm run lint:fix` —— 修复 lint 问题
|
||
|
||
生成 SSL 证书需要运行 `pnpm run ssl:generate`（使用 `generate-ssl.ts` 文件），或在运行 `pnpm run dev` 时会自动生成。
|
||
|
||
#### 后端配置
|
||
|
||
在 `.vscode/launch.json` 文件中编辑 `backend` 的配置：
|
||
- `DATABASE_URL` - PostgreSQL 数据库 URL（例如 `postgres://postgres:postgres@localhost:5432/pentagidb?sslmode=disable`）
|
||
- `DOCKER_HOST` - Docker SDK API（例如 macOS 上为 `DOCKER_HOST=unix:///Users/<my-user>/Library/Containers/com.docker.docker/Data/docker.raw.sock`）[更多信息](https://stackoverflow.com/a/62757128/5922857)
|
||
|
||
可选：
|
||
- `SERVER_PORT` - 服务器运行端口（默认：`8443`）
|
||
- `SERVER_USE_SSL` - 是否为服务器启用 SSL（默认：`false`）
|
||
|
||
##### PostgreSQL / pgvector 连接池大小
|
||
|
||
PentAGI 会向同一 Postgres 实例打开两个独立的连接池：
|
||
|
||
| 连接池 | 环境变量 | 默认值 | 使用者 |
|
||
|---|---|---|---|
|
||
| 共享 `sql.DB` | `DATABASE_MAX_OPEN_CONNS` | `25` | 所有 sqlc 查询与 GORM handler 共享同一个 `*sql.DB` |
|
||
| 共享 `pgxpool` | `DATABASE_VECTOR_MAX_CONNS` | `10` | 所有 pgvector 存储（agent memory + knowledge API）共享同一个连接池 |
|
||
|
||
额外调优参数：
|
||
- `DATABASE_MAX_IDLE_CONNS` — `sql.DB` 连接池在请求之间保持打开的最大空闲连接数（默认：`5`）。
|
||
|
||
**标准 `vxcontrol/pgvector` 镜像的连接预算**（`max_connections = 100`、`superuser_reserved_connections = 3`）：
|
||
|
||
```
|
||
Available for client connections = 97
|
||
pentagi sql.DB (DATABASE_MAX_OPEN_CONNS) = 25
|
||
pentagi pgxpool (DATABASE_VECTOR_MAX_CONNS) = 10
|
||
pgexporter = 3
|
||
autovacuum workers = 3
|
||
─────────────────────────────────────────
|
||
Total consumed = 41
|
||
Free buffer = 56 (≈ 58 %)
|
||
```
|
||
|
||
默认配置面向 **10 个并行 flow** 及并发 API 请求。若运行更多 flow，或在同一 Postgres 上部署多个 PentAGI 实例，请通过 `docker-compose.yml` 中的 `command` 覆盖提高 `max_connections`，并同比例增大连接池大小：
|
||
|
||
```yaml
|
||
pgvector:
|
||
image: vxcontrol/pgvector:latest
|
||
command: postgres -c max_connections=200
|
||
```
|
||
|
||
若要查看运行中部署的实时连接预算：
|
||
|
||
```bash
|
||
# Postgres limits
|
||
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
|
||
"SELECT name, setting FROM pg_settings
|
||
WHERE name IN ('"'"'max_connections'"'"', '"'"'superuser_reserved_connections'"'"');"'
|
||
|
||
# Current usage vs. available
|
||
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
|
||
"SELECT max_conn, used, max_conn - used AS available
|
||
FROM (SELECT current_setting('"'"'max_connections'"'"')::int AS max_conn,
|
||
count(*) AS used FROM pg_stat_activity) t;"'
|
||
|
||
# Breakdown by client
|
||
docker exec pgvector sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
|
||
"SELECT application_name, client_addr, state, count(*)
|
||
FROM pg_stat_activity
|
||
WHERE pid <> pg_backend_pid()
|
||
GROUP BY 1, 2, 3 ORDER BY count DESC;"'
|
||
```
|
||
|
||
#### 前端配置
|
||
|
||
在 `.vscode/launch.json` 文件中编辑 `frontend` 的配置：
|
||
- `VITE_API_URL` - 后端 API URL。*省略* URL scheme（例如 `localhost:8080`，*而非* `http://localhost:8080`）
|
||
- `VITE_USE_HTTPS` - 是否为服务器启用 SSL（默认：`false`）
|
||
- `VITE_PORT` - 服务器运行端口（默认：`8000`）
|
||
- `VITE_HOST` - 服务器运行主机（默认：`0.0.0.0`）
|
||
|
||
### 运行应用
|
||
|
||
#### 后端
|
||
|
||
在 `backend` 文件夹中运行以下命令：
|
||
- 使用 `.env` 文件设置环境变量，如同 `source .env`
|
||
- 运行 `go run cmd/pentagi/main.go` 启动服务器
|
||
|
||
> [!NOTE]
|
||
> 首次运行可能耗时较长，因为需要下载依赖和 docker 镜像以配置后端环境。
|
||
|
||
#### 前端
|
||
|
||
在 `frontend` 文件夹中运行以下命令：
|
||
- 运行 `pnpm install` 安装依赖
|
||
- 运行 `pnpm run dev` 启动 Web 应用
|
||
- 运行 `pnpm run build` 构建 Web 应用
|
||
|
||
打开浏览器并访问 Web 应用 URL。
|
||
|
||
## 测试 LLM Agent
|
||
|
||
PentAGI 包含名为 `ctester` 的强大工具，用于测试和验证 LLM agent 能力。该工具可帮助确保你的 LLM 提供商配置能与不同 agent 类型正确配合，从而针对各 agent 角色优化模型选择。
|
||
|
||
该工具支持多 agent 并行测试、详细报告和灵活配置选项。
|
||
|
||
### 主要特性
|
||
|
||
- **并行测试（Parallel Testing）**：同时测试多个 agent，更快获得结果
|
||
- **全面测试套件（Comprehensive Test Suite）**：评估基础补全、JSON 响应、function calling 及渗透测试知识
|
||
- **详细报告（Detailed Reporting）**：生成包含成功率与性能指标的 markdown 报告
|
||
- **灵活配置（Flexible Configuration）**：按需测试特定 agent 或测试组
|
||
- **专用测试组（Specialized Test Groups）**：包含面向网络安全与渗透测试场景的领域专项测试
|
||
|
||
### 使用场景
|
||
|
||
#### 面向开发者（本地 Go 环境）
|
||
|
||
若已克隆仓库并安装 Go：
|
||
|
||
```bash
|
||
# Default configuration with .env file
|
||
cd backend
|
||
go run cmd/ctester/*.go -verbose
|
||
|
||
# Custom provider configuration
|
||
go run cmd/ctester/*.go -config ../examples/configs/openrouter.provider.yml -verbose
|
||
|
||
# Generate a report file
|
||
go run cmd/ctester/*.go -config ../examples/configs/deepinfra.provider.yml -report ../test-report.md
|
||
|
||
# Test specific agent types only
|
||
go run cmd/ctester/*.go -agents simple,simple_json,primary_agent -verbose
|
||
|
||
# Test specific test groups only
|
||
go run cmd/ctester/*.go -groups basic,advanced -verbose
|
||
```
|
||
|
||
#### 面向用户（使用 Docker 镜像）
|
||
|
||
若希望使用预构建 Docker 镜像、无需搭建开发环境：
|
||
|
||
```bash
|
||
# Using Docker to test with default environment
|
||
docker run --rm -v $(pwd)/.env:/opt/pentagi/.env vxcontrol/pentagi /opt/pentagi/bin/ctester -verbose
|
||
|
||
# Test with your custom provider configuration
|
||
docker run --rm \
|
||
-v $(pwd)/.env:/opt/pentagi/.env \
|
||
-v $(pwd)/my-config.yml:/opt/pentagi/config.yml \
|
||
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/config.yml -agents simple,primary_agent,coder -verbose
|
||
|
||
# Generate a detailed report
|
||
docker run --rm \
|
||
-v $(pwd)/.env:/opt/pentagi/.env \
|
||
-v $(pwd):/opt/pentagi/output \
|
||
vxcontrol/pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/output/report.md
|
||
```
|
||
|
||
#### 使用预配置的提供商
|
||
|
||
Docker 镜像内置了对主流提供商（OpenAI、Anthropic、Gemini、Ollama）的支持，并为其他服务（OpenRouter、DeepInfra、DeepSeek、Moonshot、Novita）提供了预配置的提供商文件：
|
||
|
||
```bash
|
||
# Test with OpenRouter configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/openrouter.provider.yml
|
||
|
||
# Test with DeepInfra configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepinfra.provider.yml
|
||
|
||
# Test with DeepSeek configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -provider deepseek
|
||
|
||
# Test with GLM configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -provider glm
|
||
|
||
# Test with Kimi configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -provider kimi
|
||
|
||
# Test with Qwen configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -provider qwen
|
||
|
||
# Test with DeepSeek configuration file for custom provider
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepseek.provider.yml
|
||
|
||
# Test with Moonshot configuration file for custom provider
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/moonshot.provider.yml
|
||
|
||
# Test with Novita configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/novita.provider.yml
|
||
|
||
# Test with OpenAI configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -type openai
|
||
|
||
# Test with Anthropic configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -type anthropic
|
||
|
||
# Test with Gemini configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -type gemini
|
||
|
||
# Test with AWS Bedrock configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -type bedrock
|
||
|
||
# Test with Custom OpenAI configuration
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml
|
||
|
||
# Test with Ollama configuration (local inference)
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-llama318b.provider.yml
|
||
|
||
# Test with Ollama Qwen3 32B configuration (requires custom model creation)
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml
|
||
|
||
# Test with Ollama QwQ 32B configuration (requires custom model creation and 71.3GB VRAM)
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwq32b-fp16-tc.provider.yml
|
||
```
|
||
|
||
要使用这些配置，你的 `.env` 文件只需包含：
|
||
|
||
```
|
||
LLM_SERVER_URL=https://openrouter.ai/api/v1 # or https://api.deepinfra.com/v1/openai or https://api.openai.com/v1 or https://api.novita.ai/openai
|
||
LLM_SERVER_KEY=your_api_key
|
||
LLM_SERVER_MODEL= # Leave empty, as models are specified in the config
|
||
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/openrouter.provider.yml # or deepinfra.provider.ymll or custom-openai.provider.yml or novita.provider.yml
|
||
LLM_SERVER_PROVIDER= # Provider name for LiteLLM proxy (e.g., openrouter, deepseek, moonshot, novita)
|
||
LLM_SERVER_LEGACY_REASONING=false # Controls reasoning format, for OpenAI must be true (default: false)
|
||
LLM_SERVER_PRESERVE_REASONING=false # Preserve reasoning content in multi-turn conversations (required by Moonshot, default: false)
|
||
|
||
# For OpenAI (official API)
|
||
OPEN_AI_KEY=your_openai_api_key # Your OpenAI API key
|
||
OPEN_AI_SERVER_URL=https://api.openai.com/v1 # OpenAI API endpoint
|
||
|
||
# For Anthropic (Claude models)
|
||
ANTHROPIC_API_KEY=your_anthropic_api_key # Your Anthropic API key
|
||
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1 # Anthropic API endpoint
|
||
|
||
# For Gemini (Google AI)
|
||
GEMINI_API_KEY=your_gemini_api_key # Your Google AI API key
|
||
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com # Google AI API endpoint
|
||
|
||
# For AWS Bedrock (enterprise foundation models)
|
||
BEDROCK_REGION=us-east-1 # AWS region for Bedrock service
|
||
# Authentication (choose one method, priority: DefaultAuth > BearerToken > AccessKey):
|
||
BEDROCK_DEFAULT_AUTH=false # Use AWS SDK credential chain (env vars, EC2 role, ~/.aws/credentials)
|
||
BEDROCK_BEARER_TOKEN= # Bearer token authentication (takes priority over static credentials)
|
||
BEDROCK_ACCESS_KEY_ID=your_aws_access_key # AWS access key ID (static credentials)
|
||
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key # AWS secret access key (static credentials)
|
||
BEDROCK_SESSION_TOKEN= # AWS session token (optional, for temporary credentials with static auth)
|
||
BEDROCK_SERVER_URL= # Optional custom Bedrock endpoint (VPC endpoints, local testing)
|
||
|
||
# For Ollama (local server or cloud)
|
||
OLLAMA_SERVER_URL= # Local: http://ollama-server:11434, Cloud: https://ollama.com
|
||
OLLAMA_SERVER_API_KEY= # Required for Ollama Cloud (https://ollama.com/settings/keys), leave empty for local
|
||
OLLAMA_SERVER_MODEL=
|
||
OLLAMA_SERVER_CONFIG_PATH=
|
||
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=
|
||
OLLAMA_SERVER_PULL_MODELS_ENABLED=
|
||
OLLAMA_SERVER_LOAD_MODELS_ENABLED=
|
||
|
||
# For DeepSeek (Chinese AI with strong reasoning)
|
||
DEEPSEEK_API_KEY= # DeepSeek API key
|
||
DEEPSEEK_SERVER_URL=https://api.deepseek.com # DeepSeek API endpoint
|
||
DEEPSEEK_PROVIDER= # Optional: LiteLLM prefix (e.g., 'deepseek')
|
||
|
||
# For GLM (Zhipu AI)
|
||
GLM_API_KEY= # GLM API key
|
||
GLM_SERVER_URL=https://api.z.ai/api/paas/v4 # GLM API endpoint (international)
|
||
GLM_PROVIDER= # Optional: LiteLLM prefix (e.g., 'zai')
|
||
|
||
# For Kimi (Moonshot AI)
|
||
KIMI_API_KEY= # Kimi API key
|
||
KIMI_SERVER_URL=https://api.moonshot.ai/v1 # Kimi API endpoint (international)
|
||
KIMI_PROVIDER= # Optional: LiteLLM prefix (e.g., 'moonshot')
|
||
|
||
# For Qwen (Alibaba Cloud DashScope)
|
||
QWEN_API_KEY= # Qwen API key
|
||
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1 # Qwen API endpoint (US)
|
||
QWEN_PROVIDER= # Optional: LiteLLM prefix (e.g., 'dashscope')
|
||
|
||
# For Ollama (local inference) use variables above
|
||
OLLAMA_SERVER_URL=http://localhost:11434
|
||
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
|
||
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
|
||
OLLAMA_SERVER_PULL_MODELS_ENABLED=false
|
||
OLLAMA_SERVER_LOAD_MODELS_ENABLED=false
|
||
```
|
||
|
||
#### 在未验证组织中使用 OpenAI
|
||
|
||
对于所属组织未验证、无法使用最新推理模型（o1、o3、o4-mini）的 OpenAI 账户，你需要使用自定义配置。
|
||
|
||
若要在未验证组织账户下使用 OpenAI，请按如下方式配置你的 `.env` 文件：
|
||
|
||
```bash
|
||
LLM_SERVER_URL=https://api.openai.com/v1
|
||
LLM_SERVER_KEY=your_openai_api_key
|
||
LLM_SERVER_MODEL= # Leave empty, models are specified in config
|
||
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/custom-openai.provider.yml
|
||
LLM_SERVER_LEGACY_REASONING=true # Required for OpenAI reasoning format
|
||
```
|
||
|
||
该配置使用预构建的 `custom-openai.provider.yml` 文件，将所有 Agent 类型映射到未验证组织可用的模型，使用 `o3-mini`，而非 `o1`、`o3` 和 `o4-mini` 等模型。
|
||
|
||
你可以使用以下方式测试此配置：
|
||
|
||
```bash
|
||
# Test with custom OpenAI configuration for unverified accounts
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml
|
||
```
|
||
|
||
> [!NOTE]
|
||
> `LLM_SERVER_LEGACY_REASONING=true` 设置对于 OpenAI 兼容性至关重要，因为它可确保推理参数以 OpenAI API 所期望的格式发送。
|
||
|
||
#### 使用 LiteLLM Proxy
|
||
|
||
当使用 LiteLLM proxy 访问各类 LLM 提供商时，模型名称会带有提供商前缀（例如 `moonshot/kimi-2.5`，而非 `kimi-2.5`）。若要在直接 API 访问与 LiteLLM proxy 之间共用同一套提供商配置文件，请设置 `LLM_SERVER_PROVIDER` 变量：
|
||
|
||
```bash
|
||
# Direct access to Moonshot API
|
||
LLM_SERVER_URL=https://api.moonshot.ai/v1
|
||
LLM_SERVER_KEY=your_moonshot_api_key
|
||
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/moonshot.provider.yml
|
||
LLM_SERVER_PROVIDER= # Empty for direct access
|
||
|
||
# Access via LiteLLM proxy
|
||
LLM_SERVER_URL=http://litellm-proxy:4000
|
||
LLM_SERVER_KEY=your_litellm_api_key
|
||
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/moonshot.provider.yml
|
||
LLM_SERVER_PROVIDER=moonshot # Provider prefix for LiteLLM
|
||
```
|
||
|
||
设置 `LLM_SERVER_PROVIDER=moonshot` 后，系统会自动为配置文件中的所有模型名称添加 `moonshot/` 前缀，使其与 LiteLLM 的模型命名约定兼容。
|
||
|
||
**LiteLLM 提供商名称映射：**
|
||
|
||
使用 LiteLLM proxy 时，请设置相应的 `*_PROVIDER` 变量以启用模型前缀：
|
||
|
||
- `deepseek` - 用于 DeepSeek 模型（`DEEPSEEK_PROVIDER=deepseek` → `deepseek/deepseek-v4-flash`）
|
||
- `zai` - 用于 GLM 模型（`GLM_PROVIDER=zai` → `zai/glm-4`）
|
||
- `moonshot` - 用于 Kimi 模型（`KIMI_PROVIDER=moonshot` → `moonshot/kimi-k2.5`）
|
||
- `dashscope` - 用于 Qwen 模型（`QWEN_PROVIDER=dashscope` → `dashscope/qwen-plus`）
|
||
- `openai`、`anthropic`、`gemini` - 用于主流云提供商
|
||
- `openrouter` - 用于 OpenRouter 聚合器
|
||
- `deepinfra` - 用于 DeepInfra 托管
|
||
- `novita` - 用于 Novita AI
|
||
- 你在 LiteLLM 实例中配置的任何其他提供商名称
|
||
|
||
**LiteLLM 示例：**
|
||
```bash
|
||
# Use DeepSeek models via LiteLLM proxy with model prefixing
|
||
DEEPSEEK_API_KEY=your_litellm_proxy_key
|
||
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
|
||
DEEPSEEK_PROVIDER=deepseek # Models become deepseek/deepseek-v4-flash, deepseek/deepseek-v4-pro for LiteLLM
|
||
|
||
# Direct DeepSeek API usage (no prefix needed)
|
||
DEEPSEEK_API_KEY=your_deepseek_api_key
|
||
DEEPSEEK_SERVER_URL=https://api.deepseek.com
|
||
# Leave DEEPSEEK_PROVIDER empty
|
||
```
|
||
|
||
此方法可让你：
|
||
- 在直接访问与代理访问之间共用同一套配置文件
|
||
- 在不修改配置文件的情况下切换提供商
|
||
- 通过 LiteLLM 轻松测试不同的路由策略
|
||
|
||
#### 在生产环境中运行测试
|
||
|
||
如果你已有正在运行的 PentAGI 容器，并希望测试当前配置：
|
||
|
||
```bash
|
||
# Run ctester in an existing container using current environment variables
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -verbose
|
||
|
||
# Test specific agent types with deterministic ordering
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -agents simple,primary_agent,pentester -groups basic,knowledge -verbose
|
||
|
||
# Generate a report file inside the container
|
||
docker exec -it pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/data/agent-test-report.md
|
||
|
||
# Access the report from the host
|
||
docker cp pentagi:/opt/pentagi/data/agent-test-report.md ./
|
||
```
|
||
|
||
### 命令行选项
|
||
|
||
该工具接受以下选项：
|
||
|
||
- `-env <path>` - 环境文件路径（默认：`.env`）
|
||
- `-type <provider>` - 提供商类型：`custom`、`openai`、`anthropic`、`ollama`、`bedrock`、`gemini`（默认：`custom`）
|
||
- `-config <path>` - 自定义提供商配置路径（默认：来自 `LLM_SERVER_CONFIG_PATH` 环境变量）
|
||
- `-tests <path>` - 自定义测试 YAML 文件路径（可选）
|
||
- `-report <path>` - 报告文件写入路径（可选）
|
||
- `-agents <list>` - 要测试的 agent 类型列表，以逗号分隔（默认：`all`）
|
||
- `-groups <list>` - 要运行的测试组列表，以逗号分隔（默认：`all`）
|
||
- `-verbose` - 启用详细输出，显示每个 agent 的详细测试结果
|
||
|
||
### 可用的 Agent 类型
|
||
|
||
Agent 按以下确定性顺序进行测试：
|
||
|
||
1. **simple** - 基础补全任务
|
||
2. **simple_json** - JSON 结构化响应
|
||
3. **primary_agent** - 主推理 agent
|
||
4. **assistant** - 交互式助手模式
|
||
5. **generator** - 内容生成
|
||
6. **refiner** - 内容精炼与改进
|
||
7. **adviser** - 专家建议与咨询
|
||
8. **reflector** - 自我反思与分析
|
||
9. **searcher** - 信息收集与搜索
|
||
10. **enricher** - 数据丰富与扩展
|
||
11. **coder** - 代码生成与分析
|
||
12. **installer** - 安装与配置任务
|
||
13. **pentester** - 渗透测试与安全评估
|
||
|
||
### 可用的测试组
|
||
|
||
- **basic** - 基础补全与提示响应测试
|
||
- **advanced** - 复杂推理与函数调用（function calling）测试
|
||
- **json** - JSON 格式验证与结构测试（专为 `simple_json` agent 设计）
|
||
- **knowledge** - 特定领域的网络安全与渗透测试知识测试
|
||
|
||
> **注意**：`json` 测试组专为 `simple_json` agent 类型设计，而所有其他 agent 使用 `basic`、`advanced` 和 `knowledge` 组进行测试。这种专门化可确保针对每个 agent 的预期用途实现最优测试覆盖。
|
||
|
||
### 提供商配置示例
|
||
|
||
提供商配置定义了不同 agent 类型应使用哪些模型：
|
||
|
||
```yaml
|
||
simple:
|
||
model: "provider/model-name"
|
||
temperature: 0.7
|
||
top_p: 0.95
|
||
n: 1
|
||
max_tokens: 4000
|
||
|
||
simple_json:
|
||
model: "provider/model-name"
|
||
temperature: 0.7
|
||
top_p: 1.0
|
||
n: 1
|
||
max_tokens: 4000
|
||
json: true
|
||
|
||
# ... other agent types ...
|
||
```
|
||
|
||
### 优化工作流
|
||
|
||
1. **创建基线**：使用默认配置运行测试，建立基准性能
|
||
2. **分析各 agent 的性能**：查看确定性 agent 排序，识别表现不佳的 agent
|
||
3. **测试专用配置**：使用特定于提供商的配置，为各 agent 类型尝试不同模型
|
||
4. **关注领域知识**：特别关注 knowledge 组测试，以评估网络安全专业能力
|
||
5. **验证函数调用**：确保基于工具的测试对关键 agent 类型稳定通过
|
||
6. **对比结果**：在所有测试组中寻找最佳成功率与性能
|
||
7. **部署最优配置**：在生产环境中使用优化后的配置
|
||
|
||
该工具可帮助确保你的 AI agent 为其特定任务使用最有效的模型，在优化成本的同时提升可靠性。
|
||
|
||
## 嵌入（Embedding）配置与测试
|
||
|
||
PentAGI 使用向量嵌入（vector embeddings）进行语义搜索、知识存储与记忆管理。系统支持多种嵌入提供商，可根据你的需求与偏好进行配置。
|
||
|
||
### 支持的嵌入提供商
|
||
|
||
PentAGI 支持以下嵌入提供商：
|
||
|
||
- **OpenAI**（默认）：使用 OpenAI 的文本嵌入模型
|
||
- **Ollama**：通过 Ollama 使用本地嵌入模型
|
||
- **Mistral**：Mistral AI 的嵌入模型
|
||
- **Jina**：Jina AI 的嵌入服务
|
||
- **HuggingFace**：来自 HuggingFace 的模型
|
||
- **GoogleAI**：Google 的嵌入模型
|
||
- **VoyageAI**：VoyageAI 的嵌入模型
|
||
|
||
> **OpenAI 兼容第三方**：任何提供 OpenAI `/embeddings` API 的提供商，均可通过 `EMBEDDING_PROVIDER=openai` 配合自定义 `EMBEDDING_URL` 接入。例如，**Qwen DashScope** 通过 `/compatible-mode/v1` 端点提供 `text-embedding-v4`（仅限国际版与中国大陆地区——美国区域不提供嵌入服务）。完整配置片段请参阅 [Qwen Alternative Integrations](#alternative-integrations) 小节。
|
||
|
||
<details>
|
||
<summary><b>Embedding Provider Configuration</b> (click to expand)</summary>
|
||
|
||
### 环境变量
|
||
|
||
要配置嵌入（embedding）提供方，请在 `.env` 文件中设置以下环境变量：
|
||
|
||
```bash
|
||
# Primary embedding configuration
|
||
EMBEDDING_PROVIDER=openai # Provider type (openai, ollama, mistral, jina, huggingface, googleai, voyageai)
|
||
EMBEDDING_MODEL=text-embedding-3-small # Model name to use
|
||
EMBEDDING_URL= # Optional custom API endpoint
|
||
EMBEDDING_KEY= # API key for the provider (if required)
|
||
EMBEDDING_BATCH_SIZE=100 # Number of documents to process in a batch
|
||
EMBEDDING_STRIP_NEW_LINES=true # Whether to remove new lines from text before embedding
|
||
EMBEDDING_MAX_TEXT_BYTES=8192 # Max bytes of text sent to embedding model per document (byte proxy for token limit)
|
||
|
||
# Advanced settings
|
||
PROXY_URL= # Optional proxy for all API calls
|
||
HTTP_CLIENT_TIMEOUT=600 # Timeout in seconds for external API calls (default: 600, 0 = no timeout)
|
||
TERMINAL_TOOL_TIMEOUT=1200 # Default timeout in seconds for terminal tool commands when timeout=0 or negative (range: 1–10800; values <= 0 or above 10800 are clamped to 10800 = 3 hours)
|
||
|
||
# SSL/TLS Certificate Configuration (for external communication with LLM backends and tool servers)
|
||
EXTERNAL_SSL_CA_PATH= # Path to custom CA certificate file (PEM format) inside the container
|
||
# Must point to /opt/pentagi/ssl/ directory (e.g., /opt/pentagi/ssl/ca-bundle.pem)
|
||
EXTERNAL_SSL_INSECURE=false # Skip certificate verification (use only for testing)
|
||
```
|
||
|
||
<details>
|
||
<summary><b>如何添加自定义 CA 证书</b>（点击展开）</summary>
|
||
|
||
如果你看到此错误：`tls: failed to verify certificate: x509: certificate signed by unknown authority`
|
||
|
||
**步骤 1：** 获取 PEM 格式的 CA 证书包（可包含多个证书）
|
||
|
||
**步骤 2：** 将文件放在宿主机的 SSL 目录中：
|
||
```bash
|
||
# Default location (if PENTAGI_SSL_DIR is not set)
|
||
cp ca-bundle.pem ./pentagi-ssl/
|
||
|
||
# Or custom location (if using PENTAGI_SSL_DIR in docker-compose.yml)
|
||
cp ca-bundle.pem /path/to/your/ssl/dir/
|
||
```
|
||
|
||
**步骤 3：** 在 `.env` 文件中设置路径（路径必须在容器内部）：
|
||
```bash
|
||
# The volume pentagi-ssl is mounted to /opt/pentagi/ssl inside the container
|
||
EXTERNAL_SSL_CA_PATH=/opt/pentagi/ssl/ca-bundle.pem
|
||
EXTERNAL_SSL_INSECURE=false
|
||
```
|
||
|
||
**步骤 4：** 重启 PentAGI：
|
||
```bash
|
||
docker compose restart pentagi
|
||
```
|
||
|
||
**说明：**
|
||
- `pentagi-ssl` 卷会挂载到容器内的 `/opt/pentagi/ssl`
|
||
- 可在 docker-compose.yml 中使用 `PENTAGI_SSL_DIR` 变量更改宿主机目录
|
||
- 单个 PEM 文件可包含多个证书及中间 CA
|
||
- 仅将 `EXTERNAL_SSL_INSECURE=true` 用于测试（不建议用于生产环境）
|
||
|
||
</details>
|
||
|
||
### 各提供方特定限制
|
||
|
||
各提供方有特定的限制和支持的功能：
|
||
|
||
- **OpenAI**：支持所有配置选项
|
||
- **Ollama**：不支持 `EMBEDDING_KEY`，因其使用本地模型
|
||
- **Mistral**：不支持 `EMBEDDING_MODEL` 或自定义 HTTP 客户端
|
||
- **Jina**：不支持自定义 HTTP 客户端
|
||
- **HuggingFace**：需要 `EMBEDDING_KEY`，并支持所有其他选项
|
||
- **GoogleAI**：不支持 `EMBEDDING_URL`，需要 `EMBEDDING_KEY`
|
||
- **VoyageAI**：支持所有配置选项
|
||
|
||
如果未指定 `EMBEDDING_URL` 和 `EMBEDDING_KEY`，系统将尝试使用对应的 LLM 提供方设置（例如，当 `EMBEDDING_PROVIDER=openai` 时使用 `OPEN_AI_KEY`）。
|
||
|
||
### 为何嵌入提供方需保持一致
|
||
|
||
始终使用同一嵌入提供方至关重要，原因如下：
|
||
|
||
1. **向量兼容性（Vector Compatibility）**：不同提供方产生的向量在维度和数学属性上各不相同
|
||
2. **语义一致性（Semantic Consistency）**：更换提供方可能破坏先前已嵌入文档之间的语义相似性
|
||
3. **记忆污染（Memory Corruption）**：混用不同嵌入可能导致搜索结果变差，知识库功能失效
|
||
|
||
如果更换嵌入提供方，应清空并重新索引整个知识库（见下文 `etester` 工具）。
|
||
|
||
</details>
|
||
|
||
### 嵌入测试工具（etester）
|
||
|
||
PentAGI 包含专用的 `etester` 工具，用于测试、管理和调试嵌入功能。该工具对于诊断和解决与向量嵌入及知识存储相关的问题至关重要。
|
||
|
||
<details>
|
||
<summary><b>Etester 命令</b>（点击展开）</summary>
|
||
|
||
```bash
|
||
# Test embedding provider and database connection
|
||
cd backend
|
||
go run cmd/etester/main.go test -verbose
|
||
|
||
# Show statistics about the embedding database
|
||
go run cmd/etester/main.go info
|
||
|
||
# Delete all documents from the embedding database (use with caution!)
|
||
go run cmd/etester/main.go flush
|
||
|
||
# Recalculate embeddings for all documents (after changing provider)
|
||
go run cmd/etester/main.go reindex
|
||
|
||
# Search for documents in the embedding database
|
||
go run cmd/etester/main.go search -query "How to install PostgreSQL" -limit 5
|
||
```
|
||
|
||
### 使用 Docker
|
||
|
||
如果你在 Docker 中运行 PentAGI，可在容器内使用 etester：
|
||
|
||
```bash
|
||
# Test embedding provider
|
||
docker exec -it pentagi /opt/pentagi/bin/etester test
|
||
|
||
# Show detailed database information
|
||
docker exec -it pentagi /opt/pentagi/bin/etester info -verbose
|
||
```
|
||
|
||
### 高级搜索选项
|
||
|
||
`search` 命令支持多种筛选条件以缩小结果范围：
|
||
|
||
```bash
|
||
# Filter by document type
|
||
docker exec -it pentagi /opt/pentagi/bin/etester search -query "Security vulnerability" -doc_type guide -threshold 0.8
|
||
|
||
# Filter by flow ID
|
||
docker exec -it pentagi /opt/pentagi/bin/etester search -query "Code examples" -doc_type code -flow_id 42
|
||
|
||
# All available search options
|
||
docker exec -it pentagi /opt/pentagi/bin/etester search -help
|
||
```
|
||
|
||
可用的搜索参数：
|
||
- `-query STRING`：搜索查询文本（必填）
|
||
- `-doc_type STRING`：按文档类型筛选（answer、memory、guide、code）
|
||
- `-flow_id NUMBER`：按 flow ID 筛选（正整数）
|
||
- `-answer_type STRING`：按回答类型筛选（guide、vulnerability、code、tool、other）
|
||
- `-guide_type STRING`：按指南类型筛选（install、configure、use、pentest、development、other）
|
||
- `-limit NUMBER`：最大结果数量（默认：3）
|
||
- `-threshold NUMBER`：相似度阈值（0.0-1.0，默认：0.7）
|
||
|
||
### 跨 Flow 的记忆生命周期
|
||
|
||
PentAGI 存储多种向量文档，各自用途不同：
|
||
|
||
- `memory` 记录与 flow 相关的执行历史，例如工具结果和 agent 观测
|
||
- `guide`、`answer` 和 `code` 用于可在后续运行中复用的知识
|
||
|
||
若要查看某次 engagement 中发生了什么，请使用相关的 `flow_id` 在向量存储中搜索。若希望知识在单次运行之外仍能保留，应显式将持久结果存储为 `guide`、`answer` 或 `code` 文档，而非仅依赖执行记忆。
|
||
|
||
例如，若目标存在重复出现的搭建说明、认证特性或目标专属测试方法，可指示 agent 将该信息保存为 `guide`，并在下次 engagement 开始时搜索它。若希望新 flow 以可复用上下文启动，这是当前最稳妥的工作流程。
|
||
|
||
删除 flow 会通过 PentAGI 的软删除机制将其从常规查询中移除，因此可复用知识应与各 flow 的执行历史分开管理。若启用本 README 前文所述的可选 Graphiti 知识图谱，应将其当前搜索上下文视为限定于活动 flow 或 engagement，除非你显式构建独立的跨 flow 复用工作流。
|
||
|
||
### 常见故障排查场景
|
||
|
||
1. **更换嵌入提供方后**：务必运行 `flush` 或 `reindex` 以确保一致性
|
||
2. **搜索结果不佳**：尝试调整相似度阈值，或检查嵌入是否正确生成
|
||
3. **数据库连接问题**：确认 PostgreSQL 正在运行且已安装 pgvector 扩展
|
||
4. **缺少 API 密钥**：检查所选嵌入提供方的环境变量
|
||
|
||
</details>
|
||
|
||
## 使用 ftester 进行函数测试
|
||
|
||
PentAGI 包含一款名为 `ftester` 的多功能工具，用于调试、测试和开发特定函数及 AI 智能体（agent）行为。`ctester` 侧重于测试 LLM 模型能力，而 `ftester` 则允许你直接调用各个系统函数和 AI 智能体组件，并对执行上下文进行精确控制。
|
||
|
||
### 主要特性
|
||
|
||
- **直接访问函数**：无需运行整个系统即可测试单个函数
|
||
- **Mock 模式**：使用内置 mock，无需在线 PentAGI 部署即可测试函数
|
||
- **交互式输入**：交互式填写函数参数，便于探索性测试
|
||
- **详细输出**：带颜色编码的终端输出，包含格式化的响应与错误信息
|
||
- **上下文感知测试**：在特定流程（flow）、任务（task）和子任务（subtask）的上下文中调试 AI 智能体
|
||
- **可观测性集成**：所有函数调用都会记录到 Langfuse 和 Observability 技术栈
|
||
|
||
### 使用模式
|
||
|
||
#### 命令行参数
|
||
|
||
在命令行中直接指定函数和参数来运行 ftester：
|
||
|
||
```bash
|
||
# Basic usage with mock mode
|
||
cd backend
|
||
go run cmd/ftester/main.go [function_name] -[arg1] [value1] -[arg2] [value2]
|
||
|
||
# Example: Test terminal command in mock mode
|
||
go run cmd/ftester/main.go terminal -command "ls -la" -message "List files"
|
||
|
||
# Using a real flow context
|
||
go run cmd/ftester/main.go -flow 123 terminal -command "whoami" -message "Check user"
|
||
|
||
# Testing AI agent in specific task/subtask context
|
||
go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 pentester -message "Find vulnerabilities"
|
||
```
|
||
|
||
#### 交互模式
|
||
|
||
不带参数运行 ftester，获得引导式交互体验：
|
||
|
||
```bash
|
||
# Start interactive mode
|
||
go run cmd/ftester/main.go [function_name]
|
||
|
||
# For example, to interactively fill browser tool arguments
|
||
go run cmd/ftester/main.go browser
|
||
```
|
||
|
||
<details>
|
||
<summary><b>可用函数</b>（点击展开）</summary>
|
||
|
||
### 环境函数
|
||
- **terminal**：在容器中执行命令并返回输出
|
||
- **file**：在容器中执行文件操作（读取、写入、列出）
|
||
|
||
### 搜索函数
|
||
- **browser**：访问网站并截取屏幕截图
|
||
- **google**：使用 Google Custom Search 搜索网络
|
||
- **duckduckgo**：使用 DuckDuckGo 搜索网络
|
||
- **tavily**：使用 Tavily AI 搜索引擎进行搜索
|
||
- **traversaal**：使用 Traversaal AI 搜索引擎进行搜索
|
||
- **perplexity**：使用 Perplexity AI 进行搜索
|
||
- **sploitus**：搜索安全漏洞利用、漏洞（CVE）和渗透测试工具
|
||
- **searxng**：使用 Searxng 元搜索引擎进行搜索（聚合多个引擎的结果）
|
||
|
||
### 向量数据库函数
|
||
- **search_in_memory**：在向量数据库中搜索信息
|
||
- **search_guide**：在向量数据库中查找指导文档
|
||
- **search_answer**：在向量数据库中查找问题的答案
|
||
- **search_code**：在向量数据库中查找代码示例
|
||
|
||
### AI 智能体函数
|
||
- **advice**：从 AI 智能体获取专家建议
|
||
- **coder**：请求生成或修改代码
|
||
- **maintenance**：运行系统维护任务
|
||
- **memorist**：在向量数据库中存储和组织信息
|
||
- **pentester**：执行安全测试和漏洞分析
|
||
- **search**：跨多个来源进行复杂搜索
|
||
|
||
### 工具函数
|
||
- **describe**：显示有关流程、任务和子任务的信息
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>调试流程上下文</b>（点击展开）</summary>
|
||
|
||
`describe` 函数提供流程内任务和子任务的详细信息。当 PentAGI 遇到问题或卡住时，这对于诊断问题特别有用。
|
||
|
||
```bash
|
||
# List all flows in the system
|
||
go run cmd/ftester/main.go describe
|
||
|
||
# Show all tasks and subtasks for a specific flow
|
||
go run cmd/ftester/main.go -flow 123 describe
|
||
|
||
# Show detailed information for a specific task
|
||
go run cmd/ftester/main.go -flow 123 -task 456 describe
|
||
|
||
# Show detailed information for a specific subtask
|
||
go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 describe
|
||
|
||
# Show verbose output with full descriptions and results
|
||
go run cmd/ftester/main.go -flow 123 describe -verbose
|
||
```
|
||
|
||
该函数可帮助你定位流程可能卡住的精确位置，并通过直接调用相应的智能体函数来恢复处理。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>函数帮助与发现</b>（点击展开）</summary>
|
||
|
||
每个函数都有帮助模式，可显示可用参数：
|
||
|
||
```bash
|
||
# Get help for a specific function
|
||
go run cmd/ftester/main.go [function_name] -help
|
||
|
||
# Examples:
|
||
go run cmd/ftester/main.go terminal -help
|
||
go run cmd/ftester/main.go browser -help
|
||
go run cmd/ftester/main.go describe -help
|
||
```
|
||
|
||
你也可以不带参数运行 ftester，查看所有可用函数的列表：
|
||
|
||
```bash
|
||
go run cmd/ftester/main.go
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>输出格式</b>（点击展开）</summary>
|
||
|
||
`ftester` 工具使用颜色编码输出，便于解读：
|
||
|
||
- **蓝色标题**：章节标题和键名
|
||
- **青色 [INFO]**：一般信息消息
|
||
- **绿色 [SUCCESS]**：操作成功
|
||
- **红色 [ERROR]**：错误消息
|
||
- **黄色 [WARNING]**：警告消息
|
||
- **黄色 [MOCK]**：表示处于 mock 模式运行
|
||
- **洋红色值**：函数参数和结果
|
||
|
||
JSON 和 Markdown 响应会自动格式化，以提高可读性。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>高级使用场景</b>（点击展开）</summary>
|
||
|
||
### 调试卡住的 AI 流程
|
||
|
||
当 PentAGI 在流程中卡住时：
|
||
|
||
1. 通过 UI 暂停流程
|
||
2. 使用 `describe` 识别当前任务和子任务
|
||
3. 使用相同的任务/子任务 ID 直接调用智能体函数
|
||
4. 检查详细输出以定位问题
|
||
5. 根据需要恢复流程或手动干预
|
||
|
||
### 测试环境变量
|
||
|
||
验证 API 密钥和外部服务是否配置正确：
|
||
|
||
```bash
|
||
# Test Google search API configuration
|
||
go run cmd/ftester/main.go google -query "pentesting tools"
|
||
|
||
# Test browser access to external websites
|
||
go run cmd/ftester/main.go browser -url "https://example.com"
|
||
```
|
||
|
||
### 开发新的 AI 智能体行为
|
||
|
||
在开发新的提示词模板或智能体行为时：
|
||
|
||
1. 在 UI 中创建测试流程
|
||
2. 使用 ftester 以不同提示词直接调用智能体
|
||
3. 观察响应并相应调整提示词
|
||
4. 在 Langfuse 中查看所有函数调用的详细追踪记录
|
||
|
||
### 验证 Docker 容器配置
|
||
|
||
确保容器配置正确：
|
||
|
||
```bash
|
||
go run cmd/ftester/main.go -flow 123 terminal -command "env | grep -i proxy" -message "Check proxy settings"
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Docker 容器用法</b>（点击展开）</summary>
|
||
|
||
如果你在 Docker 中运行 PentAGI，可以在容器内使用 ftester：
|
||
|
||
```bash
|
||
# Run ftester inside the running PentAGI container
|
||
docker exec -it pentagi /opt/pentagi/bin/ftester [arguments]
|
||
|
||
# Examples:
|
||
docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 describe
|
||
docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 terminal -command "ps aux" -message "List processes"
|
||
```
|
||
|
||
这对于没有本地开发环境的生产部署特别有用。
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>与可观测性工具集成</b>（点击展开）</summary>
|
||
|
||
通过 ftester 进行的所有函数调用都会记录到：
|
||
|
||
1. **Langfuse**：捕获完整的 AI 智能体交互链，包括提示词、响应和函数调用
|
||
2. **OpenTelemetry**：记录指标、追踪和日志，用于系统性能分析
|
||
3. **终端输出**：提供函数执行的即时反馈
|
||
|
||
要访问详细日志：
|
||
|
||
- 在 Langfuse UI 中查看 AI 智能体追踪记录（通常位于 `http://localhost:4000`）
|
||
- 使用 Grafana 仪表板查看系统指标（通常位于 `http://localhost:3000`）
|
||
- 检查终端输出以获取即时的函数结果和错误信息
|
||
|
||
</details>
|
||
|
||
### 命令行选项
|
||
|
||
主工具接受以下若干选项：
|
||
|
||
- `-env <path>` - 环境文件路径（可选，默认：`.env`）
|
||
- `-provider <type>` - 要使用的提供商类型（默认：`custom`，可选：`openai`、`anthropic`、`ollama`、`bedrock`、`gemini`、`custom`）
|
||
- `-flow <id>` - 用于测试的 Flow ID（0 表示使用 mock，默认：`0`）
|
||
- `-task <id>` - 智能体上下文的 Task ID（可选）
|
||
- `-subtask <id>` - 智能体上下文的 Subtask ID（可选）
|
||
|
||
函数专属参数在函数名之后传递，格式为 `-name value`。
|
||
|
||
### 渗透测试提示词方法论
|
||
|
||
在为攻击性安全工作优化提示词时，应为智能体提供清晰的方法论，而非平铺直叙的载荷列表：
|
||
|
||
1. 首先明确范围、授权和成功标准
|
||
2. 先映射应用：角色、路由、参数、上传、集成和信任边界
|
||
3. 系统性地优先排序攻击面，而不是一次性测试所有内容
|
||
4. 在深入利用之前，用可复现的证据验证发现
|
||
5. 最后整理可直接用于报告的笔记，记录影响、前置条件和后续步骤
|
||
|
||
有关 PentAGI 专属的提示词指导，请参阅 [`backend/docs/prompt_engineering_pentagi.md`](backend/docs/prompt_engineering_pentagi.md)。如需实用的起点，可复用并调整 [`examples/prompts/base_web_pentest.md`](examples/prompts/base_web_pentest.md)，以匹配目标应用、技术栈和项目范围。
|
||
|
||
## 构建
|
||
|
||
### 构建 Docker 镜像
|
||
|
||
Docker 构建过程会自动从 git 标签嵌入版本信息。要正确为构建打上版本号，请使用提供的脚本：
|
||
|
||
#### Linux/macOS
|
||
|
||
```bash
|
||
# Load version variables
|
||
source ./scripts/version.sh
|
||
|
||
# Standard build
|
||
docker build \
|
||
--build-arg PACKAGE_VER=$PACKAGE_VER \
|
||
--build-arg PACKAGE_REV=$PACKAGE_REV \
|
||
-t pentagi:$PACKAGE_VER .
|
||
|
||
# Multi-platform build
|
||
docker buildx build \
|
||
--platform linux/amd64,linux/arm64 \
|
||
--build-arg PACKAGE_VER=$PACKAGE_VER \
|
||
--build-arg PACKAGE_REV=$PACKAGE_REV \
|
||
-t pentagi:$PACKAGE_VER .
|
||
|
||
# Build and push
|
||
docker buildx build \
|
||
--platform linux/amd64,linux/arm64 \
|
||
--build-arg PACKAGE_VER=$PACKAGE_VER \
|
||
--build-arg PACKAGE_REV=$PACKAGE_REV \
|
||
-t myregistry/pentagi:$PACKAGE_VER \
|
||
--push .
|
||
```
|
||
|
||
#### Windows（PowerShell）
|
||
|
||
```powershell
|
||
# Load version variables
|
||
. .\scripts\version.ps1
|
||
|
||
# Standard build
|
||
docker build `
|
||
--build-arg PACKAGE_VER=$env:PACKAGE_VER `
|
||
--build-arg PACKAGE_REV=$env:PACKAGE_REV `
|
||
-t pentagi:$env:PACKAGE_VER .
|
||
|
||
# Multi-platform build
|
||
docker buildx build `
|
||
--platform linux/amd64,linux/arm64 `
|
||
--build-arg PACKAGE_VER=$env:PACKAGE_VER `
|
||
--build-arg PACKAGE_REV=$env:PACKAGE_REV `
|
||
-t pentagi:$env:PACKAGE_VER .
|
||
```
|
||
|
||
#### 无版本信息的快速构建
|
||
|
||
适用于无需版本追踪的开发构建：
|
||
|
||
```bash
|
||
docker build -t pentagi:dev .
|
||
```
|
||
|
||
> [!NOTE]
|
||
> - 构建脚本会自动根据 git 标签确定版本
|
||
> - 发布构建（在标签提交上）没有修订后缀
|
||
> - 开发构建（标签之后）将提交哈希作为修订号（例如，`1.1.0-bc6e800`）
|
||
> - 要在本地使用构建的镜像，请在 `docker-compose.yml` 中更新镜像名称，或使用 `build` 选项
|
||
|
||
## 致谢
|
||
|
||
本项目的实现得益于以下研究与开发成果：
|
||
- [面向 LLM 应用的新兴架构](https://lilianweng.github.io/posts/2023-06-23-agent)
|
||
- [自主 LLM 智能体综述](https://arxiv.org/abs/2403.08299)
|
||
- [Codel](https://github.com/semanser/codel) by Andriy Semenets - 基于智能体的自动化初期架构灵感
|
||
|
||
## 许可证
|
||
|
||
**PentAGI** 根据 [MIT License](LICENSE) 授权。
|
||
|
||
Copyright (c) 2025 PentAGI Development Team
|
||
|
||
### 第三方依赖
|
||
|
||
所有第三方依赖均采用与 MIT 兼容的许可证。详见 [licenses/](licenses/) 目录中的详细许可证报告。
|
||
|
||
### VXControl Cloud Services
|
||
|
||
⚠️ **注意：** 虽然 VXControl Cloud SDK 代码采用 MIT 许可证，但访问 **VXControl Cloud Services**（威胁情报、AI 支持、高级功能）需要单独的 License Key，并须遵守 [服务条款](https://github.com/vxcontrol/cloud#license-and-terms).
|
||
|
||
SDK 代码本身可免费使用——服务访问需要注册。
|
||
|
||
如有疑问，请联系：**info@pentagi.com** 或 **info@vxcontrol.com**
|