Metadata-Version: 2.4
Name: ms-modelselect
Version: 0.2.0
Summary: ModelSelect: A Unified Framework for Holistic Evaluation and Quality Reward
Author-email: Qiao Cai <qiao.cai@alibaba-inc.com>, Haoran Chen <congling.chr@alibaba-inc.com>, Yuhao Cui <cyh262498@alibaba-inc.com>, Jiaji Deng <dengjiaji.djj@alibaba-inc.com>, Yiwen Ding <dingyiwen.dyw@antgroup.com>, Qingxu Fu <fuqingxu.fqx@alibaba-inc.com>, Yuan Gao <yunze.gy@alibaba-inc.com>, Sen Huang <huangsen.huang@alibaba-inc.com>, Weidan Kong <weidan.kong@alibaba-inc.com>, Li Yu <jinli.yl@alibaba-inc.com>, Boyin Liu <liuboyin.lby@alibaba-inc.com>, Zhaoyang Liu <jingmu.lzy@alibaba-inc.com>, Yunzhou Shi <yunzhou.syz@alibaba-inc.com>, Lipeng Xie <xielipeng.xlp@alibaba-inc.com>, Yunpeng Zhai <zhaiyunpeng.zyp@alibaba-inc.com>, Wei Zhang <w.zhang@alibaba-inc.com>, Zhuo Zhang <zz297429@alibaba-inc.com>, Anni Zou <zouanni.zan@alibaba-inc.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/agentscope-ai/ModelSelect
Project-URL: Repository, https://github.com/agentscope-ai/ModelSelect
Project-URL: Documentation, https://agentscope-ai.github.io/ModelSelect/
Keywords: deep-learning,evaluation,ai-model,llm
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas<3.0.0,>=2.2.3
Requires-Dist: loguru<0.8.0,>=0.7.3
Requires-Dist: json_repair<1.0.0,>=0.54.0
Requires-Dist: pydantic<3.0.0,>=2.11.5
Requires-Dist: openai<2.0.0,>=1.92.0
Requires-Dist: tenacity<10.0.0,>=9.1.0
Requires-Dist: math-verify<0.8.0,>=0.7.0
Requires-Dist: tqdm<5.0.0,>=4.66.0
Requires-Dist: fire
Requires-Dist: numpy<2.0.0,>=1.22.0
Requires-Dist: dashscope>=1.19.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: nltk>=3.8.1
Requires-Dist: jieba>=0.42.1
Requires-Dist: sacrebleu>=2.0.0
Requires-Dist: rouge-score>=0.1.2
Requires-Dist: python-Levenshtein>=0.20.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest<9.0.0,>=8.3.5; extra == "dev"
Requires-Dist: sphinx-gallery; extra == "dev"
Requires-Dist: furo; extra == "dev"
Requires-Dist: myst_parser; extra == "dev"
Requires-Dist: anyio; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-tornasync; extra == "dev"
Requires-Dist: pytest-trio; extra == "dev"
Requires-Dist: pytest-twisted; extra == "dev"
Requires-Dist: twisted; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Requires-Dist: matplotlib<4.0.0,>=3.7.0; extra == "dev"
Provides-Extra: verl
Requires-Dist: transformers<5.0.0,>=4.52.4; extra == "verl"
Requires-Dist: verl; extra == "verl"
Provides-Extra: saas
Requires-Dist: fastapi<0.120.0,>=0.109.0; extra == "saas"
Requires-Dist: uvicorn[standard]<0.35.0,>=0.27.0; extra == "saas"
Requires-Dist: sqlalchemy<2.1.0,>=2.0.25; extra == "saas"
Requires-Dist: aiomysql<0.3.0,>=0.2.0; extra == "saas"
Requires-Dist: pymysql<1.2.0,>=1.1.0; extra == "saas"
Requires-Dist: alembic<2.0.0,>=1.13.0; extra == "saas"
Requires-Dist: email-validator<3.0.0,>=2.1.0; extra == "saas"
Requires-Dist: pydantic-settings<3.0.0,>=2.1.0; extra == "saas"
Requires-Dist: python-jose[cryptography]<4.0.0,>=3.3.0; extra == "saas"
Requires-Dist: passlib[bcrypt]<1.8.0,>=1.7.4; extra == "saas"
Requires-Dist: python-multipart<0.1.0,>=0.0.6; extra == "saas"
Requires-Dist: minio<8.0.0,>=7.2.0; extra == "saas"
Requires-Dist: redis<6.0.0,>=5.0.0; extra == "saas"
Requires-Dist: httpx<0.28.0,>=0.26.0; extra == "saas"
Requires-Dist: requests<3.0.0,>=2.31.0; extra == "saas"
Provides-Extra: all
Requires-Dist: ms-modelselect[dev,saas,verl]; extra == "all"
Dynamic: license-file

<div align="center">

<img src="./docs/images/logo.svg" alt="ModelSelect Logo" width="500">

<br/>

<h3>
  <em>模型智选，评测先行：让 AI 选型更简单</em>
</h3>

<p>
  🌟 <em>If you find ModelSelect helpful, please give us a <b>Star</b>!</em> 🌟
</p>

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue?logo=python)](https://pypi.org/project/ms-modelselect/)
[![PyPI](https://img.shields.io/badge/pypi-v0.3.0-blue?logo=pypi)](https://pypi.org/project/ms-modelselect/)
[![Documentation](https://img.shields.io/badge/docs-online-blue?logo=readthedocs&logoColor=white)](https://github.com/modelselect/modelselect)

[📖 Documentation](https://github.com/modelselect/modelselect) | [🤝 Contributing](https://github.com/modelselect/modelselect) | [中文](./README_zh.md)

</div>




ModelSelect (模选) 是一个**开源的 AI 模型评测框架**，专为**AI 应用**（如 AI 智能体、聊天机器人、大语言模型）的**质量评估**和**持续优化**而设计。

> 在实践中，卓越的应用取决于可信赖的评测工作流：收集测试数据 → 定义评分标准 → 规模化运行评测 → 分析薄弱环节 → 快速迭代优化。

ModelSelect 提供**开箱即用的评分器(Grader)**，并支持生成**场景特定的评分标准**，使这一工作流**更简单**、**更专业**、**易于集成**到您的工作流中。同时，它还能将评分结果转换为**奖励信号**，帮助您**微调**和优化应用。

---

## 📑 Table of Contents

- [Key Features](#-key-features)
- [News](#news)
- [Installation](#-installation)
- [Quickstart](#-quickstart)
- [API Service](#-api-service)
- [Contributing](#-contributing)
- [Community](#-community)
- [Citation](#-citation)
---

## ✨ Key Features

### 📦 系统化且质量保障的 Grader 库

访问 **50+ 生产级评分器**，涵盖全面的分类体系，经过严格验证确保可靠性能。

<table>
<tr>
<td width="33%" valign="top">

#### 🎯 通用能力

**聚焦:** 语义质量、功能正确性、结构合规性

**核心评分器:**
- `Relevance` - 语义相关性评分
- `Similarity` - 文本相似度测量
- `Syntax Check` - 代码语法验证
- `JSON Match` - 结构合规性检查

</td>
<td width="33%" valign="top">

#### 🤖 智能体评估

**聚焦:** 智能体生命周期、工具调用、记忆、计划可行性、轨迹质量

**核心评分器:**
- `Tool Selection` - 工具选择准确性
- `Memory` - 上下文保持能力
- `Plan` - 策略可行性
- `Trajectory` - 路径优化

</td>
<td width="33%" valign="top">

#### 🖼️ 多模态评估

**聚焦:** 图文一致性、视觉生成质量、图像有用性

**核心评分器:**
- `Image Coherence` - 视觉-文本对齐
- `Text-to-Image` - 生成质量
- `Image Helpfulness` - 图像贡献度

</td>
</tr>
</table>

- 🌐 **多场景覆盖:** 广泛支持 Agent、文本、代码、数学和多模态任务等多种领域
- 🔄 ** holistic 智能体评估:** 不仅评估最终结果，还评估整个生命周期——包括轨迹、记忆、反思和工具使用
- ✅ **质量保证:** 每个评分器都附带基准数据集和 pytest 集成验证

### 🛠️ 灵活的评分器构建方式

选择适合您需求的构建方式：
* **定制化:** 需求明确但没有现成评分器？如果有明确的规则或逻辑，使用 Python 接口或 Prompt 模板快速定义自己的评分器
* **零样本评分标准生成:** 不确定使用什么标准，且没有标注数据？只需提供任务描述和可选的示例查询——LLM 将自动生成评估评分标准
* **数据驱动的评分标准生成:** 需求模糊，但有一些示例？使用 GraderGenerator 从标注数据中自动总结评估评分标准，并生成基于 LLM 的评分器
* **训练评判模型:** 数据量大且需要最佳性能？使用我们的训练流程训练专用的评判模型

### 🌐 SaaS API 服务

ModelSelect 提供完整的 SaaS API 服务，支持：
- ✅ **多租户管理**: 支持多租户隔离，每个租户独立配置
- ✅ **用户管理**: 完整的用户认证、授权和权限管理
- ✅ **评估任务**: 创建、管理和执行 AI 应用评估任务
- ✅ **场景评估**: 无需上传数据集，直接评估单个 query-response 对
- ✅ **API Key 管理**: 支持 API Key 创建和管理
- ✅ **结果分析**: 评估结果的存储、查询和统计分析

---

## News

- **2025-01-29** - ModelSelect v0.3.0 发布 - 全新品牌升级！从 OpenJudge 分支并扩展更多模型评测能力，新增 SaaS API 服务和多租户支持

---

## 📥 Installation

```bash
pip install ms-modelselect
```

安装 SaaS 服务依赖：
```bash
pip install "ms-modelselect[saas]"
```

---

## 🚀 Quickstart

### 简单示例

评估单个响应的简单示例：

```python
import asyncio
from modelselect.models import OpenAIChatModel
from modelselect.graders.common.relevance import RelevanceGrader

async def main():
    # 1️⃣ 创建模型客户端
    model = OpenAIChatModel(model="qwen3-32b")
    # 2️⃣ 初始化评分器
    grader = RelevanceGrader(model=model)
    # 3️⃣ 准备数据
    data = {
        "query": "What is machine learning?",
        "response": "Machine learning is a subset of AI that enables computers to learn from data.",
    }
    # 4️⃣ 评估
    result = await grader.aevaluate(**data)
    print(f"Score: {result.score}")   # Score: 4
    print(f"Reason: {result.reason}")

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 🌐 API Service

ModelSelect 提供完整的 SaaS API 服务，支持多租户、用户管理、评估任务管理和场景评估。

### 快速启动

```bash
# 使用 Docker Compose 启动所有服务
docker-compose up -d
```

### API 端点

| 模块 | 端点 | 功能 |
|------|------|------|
| 认证 | `POST /api/v1/auth/login` | 用户登录 |
| 认证 | `POST /api/v1/auth/register` | 用户注册 |
| 用户 | `GET /api/v1/users/me` | 获取当前用户 |
| API Key | `POST /api/v1/api-keys` | 创建 API Key |
| 任务 | `POST /api/v1/tasks` | 创建评估任务 |
| 任务 | `GET /api/v1/tasks` | 获取任务列表 |
| 场景 | `POST /api/v1/scenarios/evaluate` | 场景评估 |
| 场景 | `POST /api/v1/scenarios/batch-evaluate` | 批量场景评估 |

更多 API 文档请访问：`http://localhost:8000/docs`

---

## 🤝 Contributing

我们欢迎各种形式的贡献！请查看我们的[贡献指南](https://github.com/modelselect/modelselect)。

## 📜 License

本项目基于 Apache 2.0 许可证开源。

---

**ModelSelect Team** - 让 AI 模型选型更简单 🚀
