# 模型服务接入 - 快速上手指南

## 🚀 5分钟快速开始

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

---

## 📱 注册第一个模型

### 步骤1: 点击注册新模型
1. 在"模型服务接入"页面
2. 点击绿色"注册新模型"按钮
3. 打开模型注册对话框

### 步骤2: 填写基本信息
```yaml
模型名称: 番茄生长预测模型
模型版本: v1.0.0
模型类型: 作物生长预测 (下拉选择)
模型格式: TensorFlow (下拉选择)
```

### 步骤3: 填写模型描述
```
基于深度学习的番茄生长周期预测模型，
综合温湿度、光照等环境因素，
预测番茄的生长阶段和最佳采收时间。
```

### 步骤4: 配置输入输出格式
```yaml
输入格式: (batch, 10, 8)
输出格式: (batch, 1)

说明:
- batch: 批次大小
- 10: 时间步长（10天数据）
- 8: 特征维度（温度、湿度、光照等8个特征）
- 输出: 预测的生长天数
```

### 步骤5: 上传模型文件
1. 点击上传区域或拖拽文件
2. 选择模型文件（如 tomato_growth.pb）
3. 等待上传完成
4. 系统自动验证模型格式

### 步骤6: 配置依赖包
```
tensorflow==2.13.0
numpy==1.24.0
pandas==2.0.0
```

### 步骤7: 设置访问权限和标签
```yaml
访问权限: 团队共享 (下拉选择)
标签: 作物生长,番茄,深度学习
```

### 步骤8: 测试模型
1. 点击"测试模型"按钮
2. 系统自动执行推理测试
3. 查看测试结果
4. 看到"模型测试成功，推理正常"提示

### 步骤9: 注册并部署
1. 点击"注册并部署"按钮
2. 看到"模型服务注册成功"提示
3. 系统自动开始部署流程
4. 等待3-5分钟部署完成

**✅ 恭喜！第一个模型注册成功！**

---

## 📊 查看模型列表

### 切换到模型服务管理Tab
1. 点击"模型服务管理"标签
2. 看到所有已注册的模型列表

### 模型列表信息
```
┌─────────────┬─────────┬────────┬──────────┬────────┬──────┬────────┐
│ 模型名称     │ 类型/格式│ 版本   │ 性能指标  │ 调用统计│ 权限 │ 状态   │
├─────────────┼─────────┼────────┼──────────┼────────┼──────┼────────┤
│番茄生长预测  │作物生长  │v1.0.0  │准确率94.5%│15,680次│团队  │🟢运行中│
│模型          │TensorFlow│        │120ms     │99.2%   │共享  │        │
└─────────────┴─────────┴────────┴──────────┴────────┴──────┴────────┘
```

### 快速查看
- **性能指标**: 准确率、推理时间
- **调用统计**: 总调用次数、成功率
- **访问权限**: 公开/私有/团队共享
- **服务端点**: API地址（可复制）
- **运行状态**: 运行中/已停止/故障

---

## 🔍 查看模型详情

### 打开模型详情
1. 在模型列表中找到目标模型
2. 点击操作栏的"查看详情"按钮（眼睛图标👁️）
3. 打开模型详情对话框

### 详情内容包括

#### 1. 基本信息
- 模型名称、类型、版本
- 模型格式、作者
- 创建时间、最后更新
- 访问权限、运行状态

#### 2. 模型描述和标签
- 完整的模型描述
- 所有标签列表

#### 3. 性能指标
- **模型准确率**: 94.5%（进度条展示）
- **推理时间**: 120ms
- **调用次数**: 15,680次
- **成功率**: 99.2%

#### 4. API端点信息
```
服务端点: https://api.farm-ai.com/v1/tomato-growth
请求方式: POST
Content-Type: application/json

[复制] 按钮 - 一键复制端点地址
```

#### 5. 依赖包列表
```
✓ tensorflow==2.13.0
✓ numpy==1.24.0
✓ pandas==2.0.0
```

#### 6. API调用示例
```python
# Python调用示例
import requests

url = "https://api.farm-ai.com/v1/tomato-growth"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

payload = {
    "data": [
        [25.3, 65.2, 45820, 3.2, 1013.2, 18.5, 45.3, 2.3]
    ]
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"预测结果: {result['prediction']}")
print(f"置信度: {result['confidence']}%")
```

---

## 🔀 版本管理

### 打开版本管理
1. 在模型列表中找到目标模型
2. 点击操作栏的"版本管理"按钮（分支图标🔀）
3. 打开版本管理对话框

### 当前版本
```
版本号: v1.0.0
最后更新: 2024-10-23
状态: [生产环境]
```

### 历史版本列表
```
┌────────┬────────────┬────────┬──────────┬────────┬────────┬────────┐
│ 版本号  │ 发布时间    │ 准确率 │ 推理时间  │ 状态   │ 描述   │ 操作   │
├────────┼────────────┼────────┼──────────┼────────┼────────┼────────┤
│✓v1.0.0 │ 2024-10-23 │ 94.5% │ 120ms    │ 当前   │初始版本│  ⬇️    │
│ v0.9.0 │ 2024-10-01 │ 92.0% │ 150ms    │已归档  │测试版  │ 🔄 ⬇️  │
└────────┴────────────┴────────┴──────────┴────────┴────────┴────────┘

图例:
✓ = 当前使用版本
🔄 = 切换到此版本
⬇️ = 下载此版本
```

### 版本切换
1. 找到要切换的历史版本
2. 点击"切换"按钮（🔄）
3. 系统自动执行版本切换
4. 看到"已切换到版本 vX.Y.Z"提示

### 版本对比图表
- **准确率趋势**: 显示各版本准确率变化
- **推理时间趋势**: 显示各版本性能优化情况

---

## ⚙️ 服务配置

### 打开服务配置
1. 在模型列表中找到目标模型
2. 点击操作栏的"服务配置"按钮（⚙️）
3. 打开服务配置对话框

### 配置项

#### 1. 并发和超时
```yaml
最大并发数: 10
超时时间: 30秒
重试次数: 3次
最小实例数: 1
```

#### 2. 负载均衡
```yaml
启用负载均衡: ✓ 开启
自动分配请求到多个实例
```

#### 3. 自动伸缩
```yaml
自动伸缩: ✓ 开启
根据负载自动调整实例数量
```

#### 4. 环境变量
```
KEY=VALUE
每行一个
```

### 保存配置
1. 修改配置参数
2. 点击"保存配置"按钮
3. 看到"配置已保存"提示

---

## 🚀 模型部署

### 场景1: 新模型部署
- 在注册新模型时，点击"注册并部署"
- 系统自动完成部署

### 场景2: 重新部署
1. 在模型详情对话框中
2. 点击"重新部署"按钮
3. 打开部署配置对话框

### 部署配置

#### 1. 部署环境
```yaml
环境类型: 生产环境 (下拉选择)
  - 开发环境
  - 测试环境
  - 生产环境

部署区域: 华东 (下拉选择)
  - 华东
  - 华北
  - 华南
```

#### 2. 资源配置
```yaml
CPU配置: 2核 (下拉选择)
  - 1核 (轻量级模型)
  - 2核 (标准模型)
  - 4核 (复杂模型)
  - 8核 (大规模模型)

内存配置: 4GB (下拉选择)
  - 2GB
  - 4GB
  - 8GB
  - 16GB

GPU配置: 不使用GPU (下拉选择)
  - 不使用GPU
  - NVIDIA T4
  - NVIDIA V100
  - NVIDIA A100

副本数量: 3
```

#### 3. 自动伸缩策略
```yaml
启用自动伸缩: ✓ 开启

最小实例数: 2
最大实例数: 10
扩容阈值(CPU): 70%
缩容阈值(CPU): 30%
```

#### 4. 健康检查
```yaml
检查间隔: 30秒
超时时间: 10秒
失败阈值: 3次
成功阈值: 1次
```

### 部署流程
```
1. 模型文件准备与验证 (~1分钟)
2. 容器镜像构建 (~2分钟)
3. 服务实例启动 (~1分钟)
4. 健康检查与负载均衡配置 (~1分钟)

预计总时间: 3-5分钟
```

### 开始部署
1. 确认所有配置正确
2. 点击"开始部署"按钮
3. 看到"模型部署已启动，预计3-5分钟完成"提示
4. 系统自动执行部署流程

---

## 🎮 模型控制

### 启动服务
**适用场景**: 模型当前处于"已停止"状态

1. 在模型列表中找到停止的模型
2. 点击"启动服务"按钮（▶️）
3. 看到"模型\"XXX\"已启动"提示
4. 模型状态变为"运行中"

### 停止服务
**适用场景**: 临时维护、节省资源

1. 在模型列表中找到运行中的模型
2. 点击"停止服务"按钮（⏸️）
3. 看到"模型\"XXX\"已停止"提示
4. 模型状态变为"已停止"

### 测试推理
**适用场景**: 验证模型功能

1. 在模型详情对话框中
2. 点击"测试推理"按钮
3. 系统执行测试推理
4. 看到"模型测试成功，推理正常"提示

---

## 📋 常见操作

### 复制API端点
1. 在模型列表中找到目标模型
2. 在"服务端点"列找到复制按钮
3. 点击复制按钮（📋）
4. 看到"端点已复制到剪贴板"提示
5. 可以粘贴到代码中使用

### 搜索模型
1. 在"模型服务管理"页面
2. 在搜索框输入关键词
3. 可搜索：模型名称、类型、标签
4. 实时过滤结果

### 筛选模型
1. 使用"模型类型"下拉框
   - 全部类型
   - 作物生长预测
   - 病虫害识别
   - 产量预估
   
2. 使用"运行状态"下拉框
   - 全部状态
   - 运行中
   - 已停止

### 导出版本历史
1. 在版本管理对话框中
2. 点击"导出版本历史"按钮
3. 下载版本历史报告

---

## 💡 使用技巧

### 技巧1: 选择合适的模型格式
- **ONNX**: 生产环境首选，跨平台兼容性好
- **TensorFlow**: 深度学习模型，生态完善
- **PyTorch**: 研究和实验阶段，灵活易用
- **Scikit-learn**: 传统机器学习，轻量快速

### 技巧2: 合理配置资源
```yaml
轻量级模型 (传统ML):
  - CPU: 1-2核
  - 内存: 2-4GB
  - GPU: 不需要

中等模型 (简单DL):
  - CPU: 2-4核
  - 内存: 4-8GB
  - GPU: 可选T4

大型模型 (复杂DL):
  - CPU: 4-8核
  - 内存: 8-16GB
  - GPU: V100/A100
```

### 技巧3: 启用自动伸缩
- **开发环境**: 可以不启用，节省成本
- **测试环境**: 建议启用，模拟生产
- **生产环境**: 必须启用，应对流量波动

### 技巧4: 版本管理策略
- 生产环境运行稳定版本
- 定期发布新版本
- 保留至少3个历史版本
- 重大更新前先灰度发布

### 技巧5: 监控关键指标
定期查看：
- 准确率: 是否下降
- 推理时间: 是否增加
- 成功率: 是否降低
- CPU/内存: 是否超标

---

## ⚠️ 常见问题

### Q1: 模型上传失败怎么办？
**A**: 
1. 检查模型文件格式是否正确
2. 检查文件大小是否超过限制（建议<500MB）
3. 检查网络连接是否稳定
4. 重试上传

### Q2: 部署一直不成功？
**A**: 
1. 查看部署日志，定位错误
2. 检查依赖包是否正确
3. 验证模型文件是否完整
4. 联系技术支持

### Q3: 推理速度慢怎么优化？
**A**: 
1. 升级CPU/GPU配置
2. 增加副本数量
3. 启用负载均衡
4. 考虑模型压缩/量化

### Q4: 如何保证服务高可用？
**A**: 
1. 至少部署2个副本
2. 启用自动伸缩
3. 配置健康检查
4. 使用负载均衡
5. 多区域部署（容灾）

### Q5: 版本切换会中断服务吗？
**A**: 
不会。系统采用灰度发布策略：
1. 先启动新版本实例
2. 逐步切换流量
3. 监控新版本健康状态
4. 完全切换后停止旧版本
5. 全程零停机

---

## 📚 下一步

### 深入学习
- 阅读 `MODEL_SERVICE_ACCESS_COMPLETE.md` 了解完整功能
- 查看 `MODEL_INTEGRATION_GUIDE.md` 了解集成指南
- 阅读 API文档 了解接口细节

### 开始使用
1. ✅ 注册第一个模型
2. ✅ 配置部署参数
3. ✅ 测试模型推理
4. ✅ 监控运行状态
5. ✅ 优化性能配置

---

## 📞 需要帮助？

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

---

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

---

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