# Hotline Algorithm SDK

**Repository Path**: newpc/hotline-algorithm-sdk

## Basic Information

- **Project Name**: Hotline Algorithm SDK
- **Description**: 本目录用于开发、测试和打包热线算法平台插件。插件上传到中心平台后，由平台统一管理服务实例、模型、训练、验证、接口日志和权限；插件本身只负责算法或业务逻辑。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hotline Algorithm SDK

本目录用于开发、测试和打包热线算法平台插件。插件上传到中心平台后，由平台统一管理服务实例、模型、训练、验证、接口日志和权限；插件本身只负责算法或业务逻辑。

## 先读文档

- `插件开发说明.md`：插件结构、`algorithm.json`、接口约定、训练进度、模型管理、依赖和打包规范。
- 各插件目录下的 `README.md`：具体插件的参数、接口、训练方式和本地测试命令。
- 中心平台 `../HotlineAI Platform/README.md`：平台侧能力、训练、模型、集群和验证流程。

## 目录说明

```text
Hotline Algorithm SDK/
  classification/       # 分类类插件，例如大小类分类、ms-swift 分类
  llm/                  # 大模型对话、微调和推理类插件
  business/             # HTTP 转发、规则编排等业务插件示例
  插件开发说明.md        # 插件开发规范
  README.md             # SDK 入口说明
```

每个插件都是独立目录，上传时只压缩单个插件目录，不要压缩整个 SDK 仓库。

## 一个合格插件至少包含

```text
your_plugin/
  algorithm.json        # 平台识别插件的唯一清单
  plugin/               # Python 代码包
    __init__.py
    your_plugin.py
  requirements.txt      # 插件额外依赖，不写平台已有重型依赖的固定 CUDA wheel
  README.md             # 插件说明、参数、接口、本地测试方式
  test_plugin.py        # 最小本地测试脚本
```

带训练能力的插件还必须验证：

- `train(payload)` 能读取平台注入的 `samples`、`params.output_dir`、`params.progress_file`。
- 训练过程中按 step 写入 JSONL 进度事件，页面能看到 loss、acc、learning_rate 等中间曲线。
- 训练结束返回 `success=true`、`model_path`，模型目录可被 `load_model()` 加载。
- 收到 `cancel_file` 后能尽快停止，并尽量返回 `checkpoint_path`。
- 继续训练前会校验标签集合、模型结构和 checkpoint 兼容性。

## 开发流程

1. 复制一个同类插件作为起点，例如分类插件从 `classification/` 下选择，大模型插件从 `llm/` 下选择。
2. 修改 `algorithm.json` 的 `category`、`code`、`capability`、`name`、`entry`、`interfaces`、`config_schema` 和 `training_schema`。
3. 实现插件类，至少支持 `health()`；模型类插件还应支持 `load_model()`、`predict()`、`unload_model()`。
4. 为插件补充 `README.md` 和 `test_plugin.py`。
5. 本地执行测试脚本，确认入口、接口、模型加载和训练闭环正常。
6. 只压缩插件目录内容为 zip，上传到中心平台“插件仓库”。
7. 在平台中创建服务实例、绑定模型、启动服务并执行接口测试。
8. 如插件支持训练，在平台内跑一次小样本训练，确认训练任务、模型登记和验证评估完整闭环。

## 打包方式

进入具体插件目录，把当前目录内容压缩为 zip。zip 根目录必须直接包含 `algorithm.json`。

正确结构：

```text
classtype.zip
  algorithm.json
  plugin/
  requirements.txt
  README.md
  test_plugin.py
```

错误结构：

```text
classtype.zip
  classtype/
    algorithm.json
```

## 给 AI 写插件的提示

让 AI 写插件时，建议直接给出下面这些约束：

- 只生成一个插件目录，不改中心平台代码。
- 必须遵守 `插件开发说明.md`。
- 不要启动 Web 服务，不要写死绝对路径，不要把模型权重、数据集、缓存、密钥打包进插件。
- `algorithm.json` 必须使用 `entry.module + entry.class`。
- 所有页面展示参数都要同时有中文 `label` 和英文 `name`；复杂参数补 `description`。
- 训练插件必须写 `progress_file`，支持 `cancel_file`，训练产物写入 `output_dir`。
- 返回结构要稳定，失败时返回 `success=false` 和清晰 `message`，不要只抛底层异常。

详细字段和示例以 `插件开发说明.md` 为准。