添加 Hy3 API quickstart 示例集合

.env

@@ -0,0 +1,3 @@
+HY3_BASE_URL=https://tokenhub.tencentmaas.com/v1
+HY3_API_KEY=sk-s4wm9zZmjDJSJ1MPUFyFJ2YNaDBF2gvXLIdNWNMKdyqbJ0hp
+HY3_MODEL=hy3

.gitignore

@@ -8,3 +8,5 @@
 Thumbs.db
 __pycache__/
 *.pyc
+venv/
+.env

README.md

@@ -41,6 +41,7 @@
   - [vLLM](#vllm)
   - [SGLang](#sglang)
 - [Finetuning](#finetuning)
+- [RL Post-training](#rl-post-training)
 - [Quantization](#quantization)
 - [License](#license)
 - [Contact Us](#contact-us)
@@ -205,6 +206,10 @@ python3 -m sglang.launch_server \
 
 Hy3 provides a complete model finetuning pipeline. For detailed documentation, please refer to: [Finetuning Guide](./finetune/README.md)
 
+## RL Post-training
+
+Hy3 supports GRPO reinforcement learning training with [verl](https://github.com/volcengine/verl), training on Megatron-LM (model conversion via NVIDIA Megatron-Bridge) with vLLM rollout. For detailed documentation, please refer to: [RL Training Guide](./rl/README.md)
+
 ## Quantization
 
 We provide [AngelSlim](https://github.com/tencent/AngelSlim), a more accessible, comprehensive, and efficient toolkit for large model compression. AngelSlim supports a comprehensive suite of compression tools for large-scale multimodal models, including common quantization algorithms, low-bit quantization, and speculative sampling.

README_CN.md

@@ -41,6 +41,7 @@
   - [vLLM](#使用-vllm-推理)
   - [SGLang](#使用-sglang-推理)
 - [模型微调](#模型微调)
+- [强化学习训练](#强化学习训练)
 - [量化工具](#量化工具)
 - [许可证](#许可证)
 - [联系我们](#联系我们)
@@ -205,6 +206,10 @@ python3 -m sglang.launch_server \
 
 Hy3 提供了完整的模型微调流程，详细的微调文档请参考：[模型微调指南](./finetune/README_CN.md)
 
+## 强化学习训练
+
+Hy3 支持基于 [verl](https://github.com/volcengine/verl) 的 GRPO 强化学习训练，训练侧使用 Megatron-LM（通过 NVIDIA Megatron-Bridge 完成模型转换），rollout 侧使用 vLLM。详细文档请参考：[强化学习训练指南](./rl/README_CN.md)
+
 ## 量化工具
 
 我们提供了 [AngelSlim](https://github.com/tencent/AngelSlim)——一套易用、全面、高效的大模型压缩工具包，涵盖常用量化算法、低比特量化和投机采样等能力。

docs/01_basic_chat.md

@@ -0,0 +1,46 @@
+\# 示例 1：基础聊天
+
+
+
+\## 功能说明
+
+演示 Hy3 的单轮对话和多轮对话能力。
+
+
+
+\## 完整请求
+
+单轮对话使用 `messages` 传入单条用户消息；多轮对话通过追加 `assistant` 和 `user` 消息实现上下文传递。
+
+
+
+\## 响应解析
+
+\- `content`: 模型生成的回复
+
+\- `finish\_reason`: stop（正常结束）/ length（达到长度限制）
+
+\- `usage`: Token 用量统计
+
+
+
+\## 示例输出
+
+标题: 单轮对话
+
+回复: RESTful API 是一种基于 HTTP 协议，以资源为中心并通过标准方法（如 GET、POST、PUT、DELETE）进行无状态交互的 Web 接口设计风格。
+
+结束原因: stop
+
+Token 用量: total\_tokens=60
+
+
+
+标题: 多轮 - 第1轮
+
+回复: 在 Python 中读取 CSV 文件有多种方式...
+
+结束原因: length
+
+Token 用量: total\_tokens=331
+

docs/02_streaming.mdy

@@ -0,0 +1,69 @@
+# 示例 2：流式请求
+
+## 功能说明
+流式请求允许模型在生成完整响应之前，逐字、逐块地将内容返回给客户端。这能显著提升用户体验，让用户无需等待全部生成完毕即可开始阅读。
+
+## 适用场景
+- 聊天机器人（实时对话）
+- 内容生成（写作辅助）
+- 任何需要快速反馈的 AI 应用
+
+## 完整请求
+
+```python
+stream = client.chat.completions.create(
+    model=MODEL,
+    messages=[
+        {"role": "user", "content": "用一句话解释什么是 Docker，然后列举 3 个常用命令。"}
+    ],
+    temperature=0.7,
+    max_tokens=200,
+    stream=True,  # 开启流式
+    extra_body={"chat_template_kwargs": {"reasoning_effort": "no_think"}}
+)
+
+for chunk in stream:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="", flush=True)
+```
+
+## 响应解析
+
+| 字段 | 说明 |
+|------|------|
+| `chunk.choices[0].delta.content` | 当前流式块中的文本片段 |
+| `chunk.choices[0].finish_reason` | 在最后一个块中返回，表示结束原因 |
+| `chunk.id` | 当前块 ID（同一请求的所有块共享相同 ID） |
+| `chunk.model` | 使用的模型名称 |
+
+**关键指标：**
+- **首 Token 时延**：从请求发出到收到第一个内容块的时间，衡量"用户看到第一个字需要等多久"
+- **总耗时**：收到完整响应所需的总时间
+- **总块数**：响应被切分成的数据块数量
+
+## 示例输出
+
+```text
+Docker 是一个将应用及其依赖打包成轻量级、可移植容器的开源平台，实现"一次构建，到处运行"。
+
+常用命令：
+1. `docker run`：创建并启动容器
+2. `docker ps`：查看运行中的容器
+3. `docker build`：根据 Dockerfile 构建镜像
+
+📊 统计信息:
+   - 总块数: 36
+   - 首 Token 时延: 1.72 秒
+   - 总耗时: 2.84 秒
+   - 输出长度: 148 字符
+```
+
+## 与非流式的对比
+
+| 对比项 | 流式 | 非流式 |
+|--------|------|--------|
+| 首 Token 时延 | 短（1-3秒） | 长（需等完整生成） |
+| 用户感知等待 | 几乎即时 | 需等待数秒 |
+| 总耗时 | 略长 | 略短 |
+| 代码复杂度 | 稍复杂 | 简单 |
+| 推荐场景 | 实时交互 | 后台批处理 |

docs/03_compare.md

@@ -0,0 +1,188 @@
+\# 示例 3：流式 vs 非流式对比
+
+
+
+\## 功能说明
+
+通过同一个问题，分别使用流式和非流式两种方式请求，对比首 Token 时延、总耗时、输出长度等关键指标，帮助开发者根据场景选择合适的方式。
+
+
+
+\## 适用场景
+
+\- 接口选型评估
+
+\- 性能测试
+
+\- 用户体验优化决策
+
+
+
+\## 完整请求
+
+
+
+\### 非流式请求
+
+
+
+```python
+
+response = client.chat.completions.create(
+
+    model=MODEL,
+
+    messages=\[{"role": "user", "content": prompt}],
+
+    temperature=0.7,
+
+    max\_tokens=150,
+
+    extra\_body={"chat\_template\_kwargs": {"reasoning\_effort": "no\_think"}}
+
+)
+
+\# 等待完整响应后一次性返回
+
+```
+
+
+
+\### 流式请求
+
+
+
+```python
+
+stream = client.chat.completions.create(
+
+    model=MODEL,
+
+    messages=\[{"role": "user", "content": prompt}],
+
+    temperature=0.7,
+
+    max\_tokens=150,
+
+    stream=True,
+
+    extra\_body={"chat\_template\_kwargs": {"reasoning\_effort": "no\_think"}}
+
+)
+
+
+
+first\_token\_time = None
+
+for chunk in stream:
+
+    if first\_token\_time is None and chunk.choices\[0].delta.content:
+
+        first\_token\_time = time.time()
+
+    if chunk.choices\[0].delta.content:
+
+        content += chunk.choices\[0].delta.content
+
+```
+
+
+
+\## 响应解析
+
+
+
+\### 非流式响应
+
+| 字段 | 说明 |
+
+|------|------|
+
+| `response.choices\[0].message.content` | 完整回复内容 |
+
+| `response.usage.total\_tokens` | 总 Token 消耗量 |
+
+| `elapsed\_time` | 从请求到收到完整响应的总耗时 |
+
+
+
+\### 流式响应
+
+| 字段 | 说明 |
+
+|------|------|
+
+| `first\_token\_time` | 收到第一个内容块的时间 |
+
+| `first\_token\_latency` | 首 Token 时延（= first\_token\_time - start\_time）|
+
+| `elapsed\_time` | 收到完整响应的总耗时 |
+
+| `chunk\_count` | 响应被拆分的块数 |
+
+
+
+\## 示例输出
+
+
+
+```text
+
+ 测试 Prompt: 什么是微服务架构？请用 100 字左右概括其主要特点。
+
+
+
+ 非流式模式:
+
+    完成 (3.12秒)
+
+   内容: 微服务架构是将单一应用拆分为多个小型、独立服务的设计模式...
+
+    Token: 91
+
+
+
+ 流式模式:
+
+    完成 (3.76秒)
+
+    首 Token 时延: 2.40秒
+
+    内容: 微服务架构是将单一应用拆分为多个小型、独立服务的设计模式...
+
+   长度: 101 字符
+
+
+
+ 对比结果:
+
+   非流式总耗时: 3.12秒
+
+   流式总耗时: 3.76秒
+
+   流式首 Token 时延: 2.40秒
+
+```
+
+
+
+\## 结论与建议
+
+
+
+| 场景 | 推荐方式 | 原因 |
+
+|------|----------|------|
+
+| 实时对话/聊天 | 流式  | 用户能立即看到回复，体验好 |
+
+| 后台批量处理 | 非流式 | 代码简单，总耗时略短 |
+
+| 长文本生成 | 流式 | 用户可提前阅读，等待感弱 |
+
+| API 网关/代理 | 非流式 | 处理逻辑简单，无需流式协议 |
+
+
+
+> \*\*核心原则\*\*：流式优化的是"首屏体验"，非流式优化的是"总完成时间"。
+