Learnware项目客户端使用指南：从上传到搜索的全流程解析

项目概述

Learnware是一个开源的机器学习模型共享平台，其客户端组件Learnware Client为开发者提供了与系统交互的Python接口。通过这个客户端，开发者可以方便地上传、管理、搜索和使用平台上的各种机器学习模型（称为learnware）。本文将详细介绍客户端的核心功能和使用方法。

准备工作

获取访问凭证

在使用Learnware Client之前，需要先获取访问令牌：

1. 访问Learnware平台并登录您的账户
2. 在个人信息页面找到"Client Token"选项
3. 复制生成的令牌字符串

这个令牌将作为您客户端身份验证的凭证，请妥善保管不要泄露。

客户端初始化

首先需要初始化客户端并登录系统：

from learnware.client import LearnwareClient

# 初始化客户端实例
client = LearnwareClient()

# 使用邮箱和令牌登录系统
client.login(email="[e-mail]", token="your_access_token")

模型上传流程

创建语义规范

上传模型前需要定义语义规范(Semantic Specification)，它描述了模型的基本信息和使用场景。以下是一个表格数据分类任务的示例：

from learnware.specification import generate_semantics_spec

# 输入特征描述
input_description = {
    "Dimension": 5,
    "Description": {
        "0": "年龄",
        "1": "体重", 
        "2": "体长",
        "3": "动物类型",
        "4": "爪长"
    }
}

# 输出类别描述
output_description = {
    "Dimension": 3,
    "Description": {
        "0": "猫",
        "1": "狗",
        "2": "鸟"
    }
}

# 生成语义规范
semantic_spec = generate_semantic_spec(
    name="动物分类模型示例",
    description="一个用于动物分类的示例模型",
    data_type="Table",
    task_type="Classification",
    library_type="Scikit-learn",
    scenarios=["商业", "金融"],
    license=["Apache-2.0"],
    input_description=input_description,
    output_description=output_description
)

语义规范参数说明

创建语义规范时，各参数必须符合系统预定义的范围：

• data_type: 数据类型，必须是系统支持的类型之一
• task_type: 任务类型，如分类、回归等
• library_type: 使用的机器学习框架
• scenarios: 应用场景列表，需为系统支持场景的子集
• license: 许可证类型

可以通过client.list_semantic_specification_values(key)方法查询各参数的可选值范围。

上传模型

准备好语义规范和模型压缩包后，先进行验证再上传：

# 模型压缩包路径
zip_path = "path/to/your_model.zip"

# 上传前验证
client.check_learnware(
    learnware_zip_path=zip_path,
    semantic_specification=semantic_spec
)

# 正式上传
learnware_id = client.upload_learnware(
    learnware_zip_path=zip_path,
    semantic_specification=semantic_spec
)

上传成功后，模型会进入系统审核队列，审核通过后即可在平台中被搜索到。

模型管理

更新模型

可以更新模型的元数据或替换模型文件：

# 更新元数据
client.update_learnware(
    learnware_id="model_id_123",
    semantic_specification=new_semantic_spec
)

# 更新元数据和模型文件
client.update_learnware(
    learnware_id="model_id_123",
    semantic_specification=new_semantic_spec,
    learnware_zip_path="path/to/new_model.zip"
)

删除模型

client.delete_learnware(learnware_id="model_id_123")

模型搜索功能

Learnware系统支持多种搜索方式，可根据不同需求选择。

语义规范搜索

根据任务类型等语义信息搜索模型：

from learnware.market import BaseUserInfo

# 定义搜索条件
user_semantic = generate_semantic_spec(
    task_type="Classification"
)

# 执行搜索
user_info = BaseUserInfo(semantic_spec=user_semantic)
search_result = client.search_learnware(user_info)

统计规范搜索

基于数据的统计特征搜索更匹配的模型：

from learnware.specification import generate_stat_spec

# 生成统计规范
rkme_table = generate_stat_spec(type="table", X=train_data)

# 执行搜索
user_info = BaseUserInfo(stat_info={rkme_table.type: rkme_table})
search_result = client.search_learnware(user_info)

混合搜索

结合语义和统计信息进行更精确的搜索：

user_semantic = generate_semantic_spec(
    task_type="Classification",
    scenarios=["商业"]
)

rkme_table = generate_stat_spec(type="table", X=train_data)

user_info = BaseUserInfo(
    semantic_spec=user_semantic,
    stat_info={rkme_table.type: rkme_table}
)

search_result = client.search_learnware(user_info)

异构表格搜索

对于表格数据，当特征空间不同时可以使用异构搜索：

input_description = {
    "Dimension": 2,
    "Description": {
        "0": "叶片宽度",
        "1": "叶片长度"
    }
}

user_semantic = generate_semantic_spec(
    task_type="Classification",
    scenarios=["农业"],
    input_description=input_description
)

rkme_table = generate_stat_spec(type="table", X=train_data)

user_info = BaseUserInfo(
    semantic_spec=user_semantic,
    stat_info={rkme_table.type: rkme_table}
)

search_result = client.search_learnware(user_info)

模型使用

搜索到合适的模型后，可以下载并使用：

# 获取搜索结果中的模型ID
learnware_id = search_result["single"]["learnware_ids"][0]

# 加载模型
learnware = client.load_learnware(
    learnware_id=learnware_id,
    runnable_option="conda"  # 运行环境选项
)

# 使用模型进行预测
predictions = learnware.predict(test_data)

最佳实践建议

1. 模型验证：上传前务必使用check_learnware验证模型和规范的合法性
2. 规范完整性：提供完整的语义规范可以提高模型被搜索到的概率
3. 统计规范：尽可能提供统计规范以获得更精确的搜索结果
4. 模型更新：当模型性能提升或应用场景变化时，及时更新模型信息
5. 异构搜索：对于表格数据，当特征空间不同时尝试使用异构搜索功能

通过Learnware Client，开发者可以方便地将自己的模型共享到平台，也可以快速找到适合自己任务的现有模型，大大提高了机器学习模型的复用性和开发效率。