# 智能算法展示平台 CLI 工具使用示例

本文档提供了使用智能算法展示平台命令行工具的各种示例，涵盖从基础到高级的用法。

## 安装CLI工具

首先，安装命令行工具：

```bash
pip install algorithm-showcase-cli
```

或者直接运行Python脚本（如果您有源代码）：

```bash
python -m sdk.cli.algorithm-showcase-cli --help
```

## 配置认证

在使用CLI工具之前，需要配置API密钥：

```bash
# 设置API密钥
algorithm-showcase config set-api-key YOUR_API_KEY

# 或者设置基础URL
algorithm-showcase config set-base-url http://localhost:8000
```

您也可以通过环境变量设置：

```bash
export ALGORITHM_SHOWCASE_API_KEY=your_api_key_here
export ALGORITHM_SHOWCASE_BASE_URL=http://localhost:8000
```

## 基本操作示例

### 查看帮助

```bash
# 查看主帮助
algorithm-showcase --help

# 查看特定子命令的帮助
algorithm-showcase algorithms --help
algorithm-showcase call --help
algorithm-showcase history --help
```

### 列出所有算法

```bash
# 列出所有算法
algorithm-showcase algorithms list

# 列出特定类型的算法
algorithm-showcase algorithms list --type computer_vision

# 限制返回数量
algorithm-showcase algorithms list --limit 10

# 以JSON格式输出
algorithm-showcase algorithms list --format json
```

### 查看算法详情

```bash
# 查看特定算法的详细信息
algorithm-showcase algorithms get --algorithm-id alg-001

# 以表格形式显示版本信息
algorithm-showcase algorithms get --algorithm-id alg-001 --show-versions
```

## 算法调用示例

### 调用算法

```bash
# 基本调用（交互式输入数据）
algorithm-showcase call --algorithm-id alg-001 --version-id ver-001

# 传入JSON格式的输入数据
algorithm-showcase call \
  --algorithm-id alg-001 \
  --version-id ver-001 \
  --input-data '{"image_url": "https://example.com/sample.jpg"}'

# 传入参数
algorithm-showcase call \
  --algorithm-id alg-001 \
  --version-id ver-001 \
  --input-data '{"image_url": "https://example.com/sample.jpg"}' \
  --params '{"confidence_threshold": 0.7}'

# 从文件读取输入数据
algorithm-showcase call \
  --algorithm-id alg-001 \
  --version-id ver-001 \
  --input-file ./input.json

# 将结果保存到文件
algorithm-showcase call \
  --algorithm-id alg-001 \
  --version-id ver-001 \
  --input-data '{"image_url": "https://example.com/sample.jpg"}' \
  --output-file ./result.json
```

### 批量调用算法

```bash
# 从CSV文件批量调用算法
algorithm-showcase batch-call \
  --algorithm-id alg-001 \
  --input-file ./batch-input.csv \
  --output-file ./batch-results.json

# 从JSONL文件批量调用算法（每行一个JSON对象）
algorithm-showcase batch-call \
  --algorithm-id alg-001 \
  --input-file ./batch-input.jsonl \
  --concurrency 5  # 并发数
```

## 历史记录操作示例

### 查看调用历史

```bash
# 查看最近的调用历史
algorithm-showcase history list

# 查看特定算法的调用历史
algorithm-showcase history list --algorithm-id alg-001

# 查看特定状态的调用历史
algorithm-showcase history list --status success

# 查看特定日期范围的调用历史
algorithm-showcase history list \
  --start-date 2023-01-01 \
  --end-date 2023-01-31

# 限制返回数量
algorithm-showcase history list --limit 50

# 以表格形式显示
algorithm-showcase history list --format table
```

### 查看调用统计

```bash
# 查看总体统计
algorithm-showcase history stats

# 查看特定算法的统计
algorithm-showcase history stats --algorithm-id alg-001

# 查看今日统计
algorithm-showcase history stats --today
```

## 监控操作示例

### 查看系统健康状况

```bash
# 查看系统健康状况
algorithm-showcase monitor health

# 持续监控（类似top命令）
algorithm-showcase monitor health --watch --interval 5
```

### 查看算法性能

```bash
# 查看特定算法的性能指标
algorithm-showcase monitor performance --algorithm-id alg-001

# 查看最近30天的性能指标
algorithm-showcase monitor performance --algorithm-id alg-001 --days 30
```

## OpenAI集成示例

### 生成仿真数据

```bash
# 生成文本仿真数据
algorithm-showcase openai generate-data \
  --prompt "一段描述人工智能发展的文本" \
  --type text

# 生成图像仿真数据
algorithm-showcase openai generate-data \
  --prompt "一张包含猫和狗的照片" \
  --type image

# 生成结构化数据
algorithm-showcase openai generate-data \
  --prompt "一个包含姓名、年龄、职业的用户数据样本" \
  --type structured

# 将生成的数据保存到文件
algorithm-showcase openai generate-data \
  --prompt "一段示例文本" \
  --type text \
  --output-file ./generated-sample.txt
```

## 高级用法示例

### 使用配置文件

创建配置文件 `~/.algorithm-showcase/config.json`：

```json
{
  "api_key": "your_api_key_here",
  "base_url": "http://localhost:8000",
  "default_headers": {
    "User-Agent": "algorithm-showcase-cli/1.0"
  },
  "timeout": 30,
  "retry_count": 3
}
```

然后使用配置文件：

```bash
algorithm-showcase --config ~/.algorithm-showcase/config.json call --algorithm-id alg-001
```

### 管道操作

将多个命令连接起来：

```bash
# 获取算法列表，然后调用第一个算法
algorithm-showcase algorithms list --format json | \
jq '.algorithms[0].id' | \
xargs -I {} algorithm-showcase call --algorithm-id {}

# 生成仿真数据并立即调用算法
algorithm-showcase openai generate-data --prompt "示例数据" --type text | \
xargs -I {} algorithm-showcase call --algorithm-id alg-001 --input-data '{}'
```

### 自动化脚本示例

创建一个自动化脚本来测试算法性能：

```bash
#!/bin/bash
# performance-test.sh

ALGORITHM_ID=$1
TEST_COUNT=${2:-10}  # 默认测试10次

echo "开始测试算法 $ALGORITHM_ID 性能，共 $TEST_COUNT 次"

for i in $(seq 1 $TEST_COUNT); do
  echo "测试 $i/$TEST_COUNT"
  
  # 生成随机输入数据
  INPUT_DATA=$(algorithm-showcase openai generate-data --prompt "测试数据" --type text --format raw)
  
  # 调用算法并记录时间
  START_TIME=$(date +%s.%N)
  RESULT=$(algorithm-showcase call --algorithm-id $ALGORITHM_ID --input-data "$INPUT_DATA" --format json)
  END_TIME=$(date +%s.%N)
  
  DURATION=$(echo "$END_TIME - $START_TIME" | bc)
  echo "  响应时间: $DURATION 秒"
  
  # 检查调用是否成功
  SUCCESS=$(echo $RESULT | jq -r '.status')
  if [ "$SUCCESS" != "success" ]; then
    echo "  调用失败: $RESULT"
  fi
done

echo "测试完成，获取性能统计:"
algorithm-showcase monitor performance --algorithm-id $ALGORITHM_ID
```

使用该脚本：

```bash
chmod +x performance-test.sh
./performance-test.sh alg-001 20  # 测试20次
```

### 导出和导入数据

```bash
# 导出调用历史到CSV
algorithm-showcase history export --format csv --output-file history.csv

# 导出算法配置
algorithm-showcase algorithms export --algorithm-id alg-001 --output-file alg-config.json

# 从文件导入算法配置（如果支持）
algorithm-showcase algorithms import --input-file alg-config.json
```

## 故障排除

### 查看详细日志

```bash
# 启用调试模式
algorithm-showcase --debug call --algorithm-id alg-001

# 查看请求和响应详情
algorithm-showcase --verbose call --algorithm-id alg-001
```

### 检查网络连接

```bash
# 测试API连接
algorithm-showcase ping

# 检查认证状态
algorithm-showcase auth status
```

### 处理常见错误

```bash
# 如果收到认证错误
algorithm-showcase auth login  # 重新登录

# 如果API超时，增加超时时间
algorithm-showcase call --algorithm-id alg-001 --timeout 60

# 如果请求被限流，等待后重试或降低并发
algorithm-showcase batch-call --concurrency 1 --input-file ./input.json
```

## 环境变量

CLI工具支持以下环境变量：

```bash
export ALGORITHM_SHOWCASE_API_KEY="your_api_key"           # API密钥
export ALGORITHM_SHOWCASE_BASE_URL="http://localhost:8000" # API基础URL
export ALGORITHM_SHOWCASE_TIMEOUT="30"                     # 请求超时时间（秒）
export ALGORITHM_SHOWCASE_RETRY_COUNT="3"                  # 重试次数
export ALGORITHM_SHOWCASE_OUTPUT_FORMAT="table"            # 默认输出格式
export ALGORITHM_SHOWCASE_DEBUG="true"                     # 启用调试模式
```

这些示例展示了CLI工具的各种用法，从基本操作到高级自动化脚本。CLI工具旨在为开发者和运维人员提供一种便捷的方式来与智能算法展示平台进行交互。