# 模型服务管理 - 快速上手指南

## 🚀 访问入口

```
登录系统
  ↓
顶部导航 → "AI作物模型精准决策系统"
  ↓
侧边栏 → "模型接入集成"
  ↓
Tab页 → "模型服务管理"
```

---

## 📋 核心功能概览

模型服务管理提供7大核心功能：

1. **统一管理**: 所有模型服务集中管理
2. **元信息维护**: 编辑模型基本信息
3. **权限控制**: 管理访问权限
4. **依赖管理**: 管理运行依赖
5. **性能调优**: 优化服务性能
6. **服务配置**: 配置运行参数
7. **高可用**: 启停控制、监控

---

## 🎯 快速入门

### 场景1: 编辑模型信息

**何时使用**: 需要修改模型名称、描述、标签等基本信息

**步骤**:
1. 在模型服务管理页面，点击快捷操作区的"编辑模型"按钮
2. 或在模型列表中，点击对应模型行的操作按钮
3. 在弹出的"编辑模型信息"对话框中：
   - **基本信息**: 修改名称、类型、作者、访问权限
   - **描述和标签**: 更新模型描述、添加/删除标签
   - **性能基准**: 更新准确率、推理时间等指标
4. 点击"保存更改"按钮

**示例**:
```
原信息:
  名称: 番茄预测
  描述: 简单模型
  标签: 番茄

修改后:
  名称: 番茄生长预测模型v2
  描述: 基于深度学习的番茄生长周期预测模型，综合温湿度、光照等环境因素
  标签: 作物生长, 番茄, 深度学习, TensorFlow
```

---

### 场景2: 管理访问权限

**何时使用**: 需要控制谁可以访问模型服务

**步骤**:
1. 点击快捷操作区的"权限管理"按钮
2. 在"访问级别"区域选择：
   - **公开访问**: 任何人都可以访问（适合通用模型）
   - **团队共享**: 仅团队成员访问（适合内部协作）
   - **私有访问**: 仅所有者访问（适合敏感模型）
3. 在"授权用户"区域：
   - 输入用户名或邮箱 → 点击"添加"
   - 为每个用户设置权限级别（所有者/读取+写入/读取）
   - 点击删除按钮移除不需要的用户
4. 配置"API限流"：
   - 每秒请求数限制
   - 每天请求数限制
   - 单次批量大小限制
   - 并发连接数限制
5. （可选）配置"IP白名单"：
   - 启用IP白名单开关
   - 输入允许的IP地址或CIDR
6. 点击"保存权限设置"

**示例**:
```
访问级别: 团队共享

授权用户:
  - 张三 (zhangsan@example.com) → 所有者
  - 李四 (lisi@example.com) → 读取
  - 王五 (wangwu@example.com) → 读取+写入

API限流:
  - 每秒请求数: 100
  - 每天请求数: 10000
  - 批量大小: 32
  - 并发连接: 10

IP白名单: 已启用
  - 192.168.1.0/24
  - 10.0.0.1
```

---

### 场景3: 管理模型依赖

**何时使用**: 需要添加、更新或检查模型运行依赖

**步骤**:
1. 点击快捷操作区的"依赖管理"按钮
2. 查看"当前依赖"列表：
   - 所有已安装的依赖包
   - 版本号和安装状态
3. 操作依赖：
   - **添加**: 点击"添加依赖"按钮
   - **更新**: 点击包右侧的刷新图标
   - **删除**: 点击包右侧的删除图标
4. 检查"依赖健康":
   - 查看所有依赖是否已安装
   - 查看版本兼容性检查结果
   - 点击"重新检查依赖"按钮刷新状态
5. 处理"冲突检测":
   - 查看检测到的版本冲突
   - 阅读建议的解决方案
   - 点击"自动修复"按钮自动解决冲突
6. 配置"环境":
   - 选择Python版本
   - 选择CUDA版本（GPU支持）
7. 查看"更新历史"了解变更记录

**示例**:
```
当前依赖:
  ✓ tensorflow==2.13.0 (已安装)
  ✓ numpy==1.24.0 (已安装)
  ✓ pandas==2.0.0 (已安装)

健康检查:
  ✓ 所有依赖已安装
  ✓ 版本兼容性检查通过

冲突检测:
  ⚠️ numpy==1.24.0 与 tensorflow==2.13.0 可能不兼容
  建议: 升级 numpy 到 1.24.3
  [自动修复] ← 点击解决

环境配置:
  Python: 3.9
  CUDA: 11.8
```

---

### 场景4: 性能调优

**何时使用**: 模型性能不达标，需要优化

**步骤**:
1. 点击快捷操作区的"性能调优"按钮
2. 查看"当前性能指标":
   - 响应时间、QPS、CPU/内存使用率
3. 查看"智能优化建议":
   - 模型量化: 减少内存、提升速度
   - 批处理优化: 提升吞吐量
   - GPU加速: 大幅提升速度
   - 缓存优化: 减少重复计算
4. 配置"负载均衡策略":
   - 选择负载均衡算法（轮询/最少连接/IP哈希/加权）
   - 设置会话保持时间
   - 设置健康检查间隔
   - 启用跨区域负载均衡
5. 配置"缓存优化":
   - 启用结果缓存开关
   - 选择缓存策略（LRU/LFU/FIFO）
   - 设置缓存大小、过期时间、最大条目
6. 配置"并发控制":
   - 设置最大并发请求数
   - 设置每实例并发数
   - 设置请求队列长度和超时
7. （可选）运行"性能测试":
   - 设置并发用户数、测试时间、目标QPS
   - 点击"开始压力测试"
8. 点击"应用优化配置"

**示例**:
```
当前性能:
  - 响应时间: 115ms
  - QPS: 45.6
  - CPU: 42.5%
  - 内存: 68.3%

优化建议:
  [✓] 启用模型量化 → 减少70%内存，提升2-3倍速度
  [ ] 增加批处理大小 → 从1调整为8-16
  [ ] 启用GPU加速 → 提升10-50倍速度

负载均衡:
  - 算法: 轮询
  - 会话保持: 300秒
  - 健康检查: 30秒
  - 跨区域: 已启用

缓存配置:
  - 启用缓存: ✓
  - 策略: LRU
  - 大小: 1024MB
  - 过期: 3600秒

应用优化后预期:
  - 响应时间: 40-60ms
  - QPS: 150+
  - 内存: 20-30%
```

---

### 场景5: 启停服务控制

**何时使用**: 需要临时停止或重启模型服务

**启动服务**:
1. 在模型列表中找到状态为"已停止"的模型
2. 点击操作列的"启动服务"按钮（▶️图标）
3. 等待约30-60秒
4. 状态变为"运行中"

**停止服务**:
1. 在模型列表中找到状态为"运行中"的模型
2. 点击操作列的"停止服务"按钮（⏸️图标）
3. 系统会先停止接收新请求，等待现有请求完成
4. 等待约10-30秒
5. 状态变为"已停止"

**示例场景**:
```
临时维护:
  1. 停止服务
  2. 执行维护操作（更新依赖、修改配置等）
  3. 重新启动服务
  4. 验证服务正常

节省资源:
  - 非工作时间停止不常用的模型
  - 工作时间再启动
```

---

### 场景6: 服务配置

**何时使用**: 需要调整服务运行参数

**步骤**:
1. 在模型列表中，点击对应模型的"服务配置"按钮（⚙️图标）
2. 配置运行参数:
   - **最大并发数**: 单实例可同时处理的请求数
   - **超时时间**: 单次推理的超时限制（秒）
   - **重试次数**: 失败后的自动重试次数
   - **最小实例数**: 保持运行的最小实例数
3. 配置负载均衡:
   - 启用负载均衡开关
   - 自动分配请求到多个实例
4. 配置自动伸缩:
   - 启用自动伸缩开关
   - 根据负载自动调整实例数量
5. 配置环境变量:
   - 格式: KEY=VALUE
   - 每行一个
6. 点击"保存配置"

**示例**:
```
运行参数:
  - 最大并发数: 10
  - 超时时间: 30秒
  - 重试次数: 3次
  - 最小实例数: 2

负载均衡:
  ✓ 已启用

自动伸缩:
  ✓ 已启用

环境变量:
  MODEL_BATCH_SIZE=8
  ENABLE_GPU=true
  LOG_LEVEL=INFO
```

---

## 💡 使用技巧

### 技巧1: 合理设置访问权限

```yaml
开发阶段:
  - 使用"私有访问"
  - 仅开发者可访问
  - 避免误用

测试阶段:
  - 使用"团队共享"
  - 测试团队可访问
  - 收集反馈

生产阶段:
  - 根据实际需求选择
  - 内部使用: 团队共享
  - 对外服务: 公开访问 + API限流
```

### 技巧2: 定期检查依赖

```yaml
每周:
  - 运行依赖健康检查
  - 查看是否有新版本
  - 检查安全漏洞

每月:
  - 更新依赖到稳定版本
  - 测试兼容性
  - 更新环境配置

遇到问题:
  - 立即运行冲突检测
  - 使用自动修复功能
  - 查看更新历史定位问题
```

### 技巧3: 性能优化顺序

```yaml
第一步: 检查当前性能
  - 查看性能指标
  - 识别瓶颈（CPU/内存/网络）

第二步: 应用快速优化
  - 启用缓存（立即见效）
  - 调整批处理大小（简单有效）
  - 启用负载均衡（提升稳定性）

第三步: 深度优化
  - 模型量化（需要重新部署）
  - GPU加速（需要硬件支持）
  - 代码优化（需要修改模型）

第四步: 验证效果
  - 运行性能测试
  - 对比优化前后
  - 调整参数
```

### 技巧4: 避免服务中断

```yaml
更新配置时:
  - 先在测试环境验证
  - 使用灰度发布
  - 准备回滚方案

停止服务前:
  - 确认是否有正在处理的请求
  - 通知用户服务维护时间
  - 准备备用方案

重大变更时:
  - 创建新版本而不是修改现有版本
  - 使用版本切换功能
  - 保留旧版本以便快速回滚
```

---

## ⚠️ 常见问题

### Q1: 如何批量管理多个模型？
**A**: 
1. 目前支持单个模型管理
2. 对于批量操作，建议：
   - 导出配置文件
   - 批量修改配置文件
   - 重新导入（计划中功能）
3. 或使用API进行批量操作

### Q2: 修改配置后需要重启服务吗？
**A**: 
大部分配置支持热更新，无需重启：
- ✓ 并发数、超时时间
- ✓ 负载均衡设置
- ✓ 缓存配置
- ✓ 环境变量

需要重启的配置：
- ✗ Python版本
- ✗ CUDA版本
- ✗ 依赖包重大更新

### Q3: 依赖冲突无法自动修复怎么办？
**A**: 
1. 查看冲突详情和建议
2. 手动更新有冲突的包：
   - 点击包的更新按钮
   - 选择兼容的版本
3. 如果仍有问题：
   - 查看包的官方文档
   - 降级到之前的稳定版本
   - 联系技术支持

### Q4: 性能优化后效果不明显？
**A**: 
1. 确认优化已生效：
   - 查看配置是否已保存
   - 查看服务是否已重启（如需要）
2. 运行性能测试验证
3. 检查是否存在其他瓶颈：
   - 网络带宽
   - 数据库查询
   - 外部API调用
4. 尝试其他优化方案

### Q5: 如何回滚到之前的配置？
**A**: 
1. 暂不支持配置版本回滚（计划中）
2. 当前解决方案：
   - 定期导出配置备份
   - 记录重要配置变更
   - 手动恢复到之前的值

### Q6: 权限设置后其他用户看不到模型？
**A**: 
检查以下几点：
1. 访问级别是否设置正确
2. 用户是否在授权列表中
3. 用户权限级别是否足够
4. 用户是否已登录
5. 是否有IP白名单限制

---

## 📚 相关文档

- `MODEL_SERVICE_MANAGEMENT_COMPLETE.md` - 完整功能文档
- `MODEL_SERVICE_ACCESS_COMPLETE.md` - 模型服务接入文档
- `MODEL_SERVICE_QUICK_START.md` - 服务接入快速指南
- `README.md` - AI系统总览

---

## 🎯 最佳实践

### 1. 访问权限管理最佳实践

```yaml
原则:
  - 最小权限原则: 只给必要的权限
  - 定期审查: 每月检查授权用户列表
  - 及时清理: 离职人员立即移除
  - 权限分离: 开发、测试、生产环境分离

示例:
  开发环境:
    - 开发者: 读取+写入
    - 测试: 读取
  
  生产环境:
    - 运维: 所有者
    - 应用: 读取
    - 监控: 读取
```

### 2. 依赖管理最佳实践

```yaml
版本管理:
  - 锁定版本: 使用==而不是>=
  - 定期更新: 但不是每个新版本都更新
  - 测试验证: 更新后充分测试
  - 记录变更: 在更新历史中详细记录

示例:
  推荐:
    tensorflow==2.13.0
    numpy==1.24.3
  
  不推荐:
    tensorflow>=2.0
    numpy
```

### 3. 性能调优最佳实践

```yaml
优化策略:
  1. 先测量，后优化
  2. 优先低成本高收益的优化
  3. 一次一个变量
  4. 记录每次优化的效果

监控指标:
  - P50, P95, P99响应时间
  - QPS和错误率
  - 资源使用率
  - 缓存命中率

优化顺序:
  1. 启用缓存 (立即见效)
  2. 批处理优化 (简单有效)
  3. 负载均衡 (提升稳定性)
  4. 模型量化 (深度优化)
  5. GPU加速 (需要硬件)
```

---

## 📞 需要帮助？

如有任何问题，请：
1. 查看本指南的常见问题部分
2. 查看完整功能文档
3. 查看系统日志
4. 联系技术支持

---

**祝您使用愉快！🎉**

---

**更新时间**: 2024-10-23  
**版本**: v1.0  
**适用系统**: 智慧农业生产管理系统 - AI作物模型精准决策系统
