taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity

更新

Browse Source
This commit is contained in:
Ubuntu
2026-01-04 13:54:46 +00:00
parent 3cc233c6e9
commit 085dd9c84e
1 changed files with 216 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plans/agent-manager-requirements.md
+216 -48
View File
@@ -29,17 +29,15 @@ flowchart TB
end
subgraph AKS[Azure Kubernetes Service]
subgraph PlatformNS[平台 Agent 命名空间]
subgraph AgentNS[Agent 命名空间 - 统一]
PlatformPods[平台 Agent Pods]
end
subgraph CustomNS[自定义 Agent 命名空间]
CustomPods[自定义 Agent Pods]
end
end
subgraph ACR[Azure Container Registry]
PlatformImages[平台 Agent 镜像]
CustomImages[自定义 Agent 镜像/模板]
PlatformImages[平台 Agent 镜像仓库]
CustomImages[自定义 Agent 镜像仓库]
end
UI --> MCPServer
@@ -54,6 +52,13 @@ flowchart TB
前端 → MCP Server（权限验证、计费、配额检查）→ Agent Manager（K8s 部署操作）→ AKS
```
### 1.4 核心设计原则
1. **按需创建**：Agent Pod 在用户实际使用时才创建，不预先启动
2. **配额分配**：分配的是 Pod 数量配额，不是实际运行的 Pod
3. **镜像共享**：同一模板的镜像配置（CPU/内存）是平台级别固定的
4. **实例隔离**：每个用户使用时创建自己的 Pod 实例
---
## 2. Agent 类型定义
@@ -62,22 +67,24 @@ flowchart TB
| 属性 | 说明 |
|------|------|
| **来源** | 平台管理员打镜像到 ACR 仓库 |
| **部署方式** | K8s 部署，使用平台预设的镜像 |
| **资源配置** | 管理员固定设置每个 Pod 的 CPU/内存 |
| **分配方式** | 管理员 → 渠道 → 租户，限制最大 Pod 数量 |
| **来源** | 平台管理员打镜像到 ACR 平台镜像仓库 |
| **部署方式** | K8s 部署，使用平台预设的镜像，**按需创建 Pod** |
| **资源配置** | 管理员固定设置每个 Pod 的 CPU/内存（平台级别统一） |
| **分配方式** | 管理员设置总 Pod 上限 → 分配 Pod 数量给渠道 → 渠道分配给租户 |
| **使用方式** | 用户只需传查询参数即可使用 |
| **弹性伸缩** | 固定 1 个 Pod，可弹性扩展到设置的最大数量 |
| **Pod 创建时机** | 用户实际使用时才创建 Pod，不预先启动 |
| **弹性伸缩** | 用户可在分配的配额内启动多个 Pod |
### 2.2 自定义 Agent (Custom Agent)
| 属性 | 说明 |
|------|------|
| **来源** | 平台提供模板镜像，用户配置自己的密钥和终结点 |
| **部署方式** | K8s 部署，使用模板镜像 + 用户环境变量 |
| **资源配置** | 用户在分配的资源总量内自由配置 |
| **分配方式** | 管理员 → 渠道 → 租户，限制 CPU/内存总量 |
| **来源** | 平台提供模板镜像到 ACR 自定义镜像仓库，用户配置自己的密钥和终结点 |
| **部署方式** | K8s 部署，使用模板镜像 + 用户环境变量，**按需创建 Pod** |
| **资源配置** | 用户在分配的资源总量（CPU/内存）内自由配置每个 Pod 的大小 |
| **分配方式** | 管理员 → 渠道（分配 CPU/内存总量）→ 租户 |
| **使用方式** | 需要传终结点、密钥、查询参数等 |
| **Pod 创建时机** | 用户创建 Agent 并配置完成后启动 Pod |
| **弹性伸缩** | 可设置预留 Pod 数和弹性 Pod 数（如固定 2 个 + 弹性 2 个） |
### 2.3 两种 Agent 的核心区别
@@ -93,13 +100,66 @@ flowchart TB
│ │ 镜像: 平台预设，完整可用 │ │ 镜像: 模板，需要用户配置 │ │
│ │ 配置: 无需用户配置 │ │ 配置: 需要终结点、密钥等 │ │
│ │ 资源: 固定大小，限制 Pod 数量 │ │ 资源: 限制总量，自由分配 │ │
│ │ 弹性: 固定1个，弹性到最大数 │ │ 弹性: 预留N个 + 弹性M个 │ │
│ │ 归属: 共享，多租户可用 │ │ 归属: 独占，每个Pod属于一个用户 │ │
│ │ 弹性: 在配额内启动多个 Pod │ │ 弹性: 预留N个 + 弹性M个 │ │
│ │ 归属: 每个Pod属于一个用户 │ │ 归属: 每个Pod属于一个用户 │ │
│ │ 创建: 用户使用时按需创建 │ │ 创建: 配置完成后启动 │ │
│ └─────────────────────────────────┘ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 2.4 资源分配流程
```mermaid
flowchart TB
subgraph Admin[管理员层]
A1[设置平台Agent模板]
A2[设置CPU/内存/最大Pod数]
A3[设置自定义Agent模板]
A4[设置自定义Agent资源池]
end
subgraph Channel[渠道层]
C1[获得平台Agent Pod配额]
C2[获得自定义Agent资源配额]
C3[分配给租户]
end
subgraph Tenant[租户层]
T1[获得平台Agent Pod配额]
T2[获得自定义Agent资源配额]
end
subgraph Usage[使用层]
U1[使用平台Agent - 按需创建Pod]
U2[创建自定义Agent - 配置后启动Pod]
end
A1 --> A2
A3 --> A4
A2 --> C1
A4 --> C2
C1 --> C3
C2 --> C3
C3 --> T1
C3 --> T2
T1 --> U1
T2 --> U2
```
### 2.5 ACR 镜像仓库规划
| 仓库 | 用途 | 示例路径 |
|------|------|----------|
| 平台 Agent 镜像仓库 | 存放平台预设的完整 Agent 镜像 | `your-acr.azurecr.io/platform-agents/` |
| 自定义 Agent 镜像仓库 | 存放需要用户配置的模板镜像 | `your-acr.azurecr.io/custom-agents/` |
### 2.6 K8s 命名空间规划
| 命名空间 | 用途 |
|----------|------|
| `ai-agents` | 统一的 Agent 命名空间，包含平台 Agent 和自定义 Agent 的所有 Pod |
---
## 3. 功能需求
@@ -525,48 +585,124 @@ class CustomAgent:
### 6.1 平台 Agent 资源限制
#### 6.1.1 分配流程
```mermaid
flowchart LR
A[管理员] -->|设置模板| B[平台Agent模板]
B -->|固定配置| C[CPU/内存/最大Pod数]
A -->|分配Pod配额| D[渠道]
D -->|分配Pod配额| E[租户]
E -->|使用时创建| F[Pod实例]
```
#### 6.1.2 配额检查流程
```mermaid
flowchart TD
A[创建/扩容请求] --> B{检查 Pod 数量限制}
B -->|未超限| C[执行操作]
B -->|已超限| D[拒绝请求]
C --> E[更新 Pod 数量]
A[用户请求使用平台Agent] --> B[MCP Server 权限验证]
B --> C{检查用户Pod配额}
C -->|配额充足| D[调用 Agent Manager]
C -->|配额不足| E[拒绝请求]
D --> F[创建Pod实例]
F --> G[更新已使用Pod数]
```
**限制规则**：
- 每个 Pod 的资源配置由管理员固定
- 分配给渠道/租户时限制最大 Pod 数量
- 默认固定 1 个 Pod，可弹性扩展到最大数量
- 每个 Pod 的资源配置（CPU/内存）由管理员在模板级别固定
- 管理员设置该模板的最大 Pod 总数
- 分配给渠道时，分配的是 Pod 数量配额
- 渠道分配给租户时，分配的也是 Pod 数量配额
- 用户使用时才真正创建 Pod，按需启动
- 用户可在配额内启动多个 Pod 实例
**配额分配示例**：
```
平台 Agent: jina_search_agent
├── 模板配置: CPU=500m, Memory=512Mi, 最大Pod数=100
│
├── 渠道A 配额: 30 个 Pod
│ ├── 租户A1: 10 个 Pod 配额
│ ├── 租户A2: 15 个 Pod 配额
│ └── 租户A3: 5 个 Pod 配额
│
└── 渠道B 配额: 20 个 Pod
├── 租户B1: 12 个 Pod 配额
└── 租户B2: 8 个 Pod 配额
```
### 6.2 自定义 Agent 资源限制
#### 6.2.1 分配流程
```mermaid
flowchart LR
A[管理员] -->|设置模板| B[自定义Agent模板]
A -->|分配资源配额| C[渠道]
C -->|分配资源配额| D[租户]
D -->|在配额内创建| E[自定义Agent]
E -->|启动| F[Pod实例]
```
#### 6.2.2 配额检查流程
```mermaid
flowchart TD
A[创建/扩容请求] --> B[计算请求资源总量]
B --> C{检查资源配额}
C -->|未超限| D[执行操作]
C -->|已超限| E[拒绝请求]
D --> F[更新已使用资源]
A[用户创建自定义Agent] --> B[MCP Server 权限验证]
B --> C[计算请求资源总量]
C --> D{检查资源配额}
D -->|配额充足| E[调用 Agent Manager]
D -->|配额不足| F[拒绝请求]
E --> G[创建Pod实例]
G --> H[更新已使用资源]
```
**限制规则**：
- 分配给渠道/租户的是资源总量（CPU/内存）
- 用户在总量内自由分配，可启动多个 Pod
- 计算公式：`Pod数量 × 单Pod资源 ≤ 资源配额`
- 用户在总量内自由配置每个 Pod 的资源大小
- 计算公式：`Σ(每个Pod的资源) ≤ 资源配额`
- 支持预留 Pod 数 + 弹性 Pod 数配置
**资源计算示例**：
**配额分配示例**：
```
用户配额：4 CPU, 8GB 内存
方案1：4 个 Pod，每个 1 CPU, 2GB 内存
方案2：2 个 Pod，每个 2 CPU, 4GB 内存
方案3：预留 2 个 Pod（1 CPU, 2GB）+ 弹性 2 个 Pod（1 CPU, 2GB）
自定义 Agent 资源池
│
├── 渠道A 配额: 8 CPU, 16GB 内存
│ ├── 租户A1: 4 CPU, 8GB 内存
│ │ └── 可创建: 4个(1CPU,2GB) 或 2个(2CPU,4GB) 或混合
│ └── 租户A2: 4 CPU, 8GB 内存
│
└── 渠道B 配额: 4 CPU, 8GB 内存
└── 租户B1: 4 CPU, 8GB 内存
└── 配置: 预留2个Pod + 弹性2个Pod
```
### 6.3 弹性伸缩配置
#### 6.3.1 平台 Agent 弹性配置
| 参数 | 说明 | 示例 |
|------|------|------|
| minReplicas | 最小 Pod 数（预留） | 1 |
| maxReplicas | 最大 Pod 数（配额上限） | 5 |
**说明**：用户在 `minReplicas` 到 `maxReplicas` 范围内按需创建 Pod
#### 6.3.2 自定义 Agent 弹性配置
| 参数 | 说明 | 示例 |
|------|------|------|
| minReplicas | 预留 Pod 数（始终运行） | 2 |
| maxReplicas | 最大 Pod 数（弹性上限） | 4 |
| targetCPUUtilization | CPU 使用率阈值 | 80% |
**说明**：
- `minReplicas` 个 Pod 始终运行（预留）
- 根据负载自动扩展到 `maxReplicas`
- 总资源消耗不能超过用户配额
---
## 7. 安全考虑
@@ -576,16 +712,19 @@ flowchart TD
- 自定义 Agent 的环境变量（密钥、终结点等）需要加密存储
- 使用 K8s Secret 存储敏感信息
- API 响应中不返回敏感信息明文
- 日志中脱敏处理敏感字段
### 7.2 命名空间隔离
- 平台 Agent 和自定义 Agent 使用不同的命名空间
- 建议：`platform-agents` 和 `custom-agents`
- 所有 Agent Pod 统一部署在 `ai-agents` 命名空间
- 通过 Label 区分平台 Agent 和自定义 Agent
- 通过 Label 标记 Pod 所属的用户/渠道
### 7.3 网络策略
- 配置 NetworkPolicy 限制 Pod 间通信
- 自定义 Agent 的 Pod 之间相互隔离
- 只允许 Agent Manager 和 MCP Server 访问 Agent Pod
---
@@ -653,12 +792,12 @@ spec:
- name: agent-manager
image: your-acr.azurecr.io/agent-manager:latest
env:
- name: KUBERNETES_NAMESPACE_PLATFORM
value: "platform-agents"
- name: KUBERNETES_NAMESPACE_CUSTOM
value: "custom-agents"
- name: ACR_REGISTRY
value: "your-acr.azurecr.io"
- name: KUBERNETES_NAMESPACE
value: "ai-agents"
- name: ACR_PLATFORM_REGISTRY
value: "your-acr.azurecr.io/platform-agents"
- name: ACR_CUSTOM_REGISTRY
value: "your-acr.azurecr.io/custom-agents"
```
### 9.2 命名空间规划
@@ -666,8 +805,34 @@ spec:
| 命名空间 | 用途 |
|----------|------|
| taiji-system | 系统服务（MCP Server, Agent Manager 等） |
| platform-agents | 平台 Agent Pods |
| custom-agents | 自定义 Agent Pods |
| ai-agents | 所有 Agent Pods（平台 Agent + 自定义 Agent） |
### 9.3 ACR 镜像仓库规划
| 仓库路径 | 用途 |
|----------|------|
| `your-acr.azurecr.io/platform-agents/` | 平台 Agent 镜像（完整可用） |
| `your-acr.azurecr.io/custom-agents/` | 自定义 Agent 模板镜像（需要用户配置） |
### 9.4 Pod Label 规划
```yaml
# 平台 Agent Pod Labels
labels:
app: agent
agent-type: platform
template: jina_search_agent
owner-id: user-uuid-123
channel-id: channel-uuid-456
# 自定义 Agent Pod Labels
labels:
app: agent
agent-type: custom
template: openai_agent_template
owner-id: user-uuid-123
channel-id: channel-uuid-456
```
---
@@ -683,6 +848,8 @@ spec:
5. **备份恢复**：Agent 配置是否需要备份？
6. **Pod 命名规则**：建议格式 `{template}-{owner-id-short}-{random}`，如 `jina-search-a1b2c3-xyz123`
---
## 11. 版本历史
@@ -690,3 +857,4 @@ spec:
| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-01-04 | 初始版本 |
| v1.1 | 2026-01-04 | 更新资源限制逻辑，明确按需创建和配额分配机制 |