新增Hy3 API quickstart文档与6个完整示例代码

examples/basic_chat.py

@@ -0,0 +1,54 @@
+from openai import OpenAI
+import os
+
+# 初始化客户端
+client = OpenAI(
+    base_url="https://hy3.example.com/v1",
+    api_key=os.getenv("HY3_API_KEY", "你的API_KEY")
+)
+
+# ========== 1. 单轮对话示例 ==========
+def single_turn_chat():
+    print("=== 单轮对话 ===")
+    response = client.chat.completions.create(
+        model="hy3-base",
+        messages=[
+            {"role": "user", "content": "请用一句话介绍一下Hy3模型"}
+        ],
+        temperature=0.7,
+        max_tokens=200
+    )
+    # 解析返回结果
+    answer = response.choices[0].message.content
+    print("用户：请用一句话介绍一下Hy3模型")
+    print("助手：", answer)
+    print()
+    return answer
+
+# ========== 2. 多轮对话示例 ==========
+def multi_turn_chat():
+    print("=== 多轮对话 ===")
+    # 历史消息列表，多轮需要保留上下文
+    messages = [
+        {"role": "user", "content": "你好，我想学习Python"},
+        {"role": "assistant", "content": "你好！学习Python可以从基础语法开始，比如变量、循环、函数这些知识点。"},
+        {"role": "user", "content": "那第一步应该学什么？"}
+    ]
+
+    response = client.chat.completions.create(
+        model="hy3-base",
+        messages=messages,
+        temperature=0.7,
+        max_tokens=300
+    )
+
+    answer = response.choices[0].message.content
+    print("历史对话：")
+    for msg in messages:
+        print(f"{msg['role']}: {msg['content']}")
+    print("assistant:", answer)
+    print()
+
+if __name__ == "__main__":
+    single_turn_chat()
+    multi_turn_chat()

examples/error_retry.py

@@ -0,0 +1,70 @@
+from openai import OpenAI
+from openai import APIError, RateLimitError, APIConnectionError, Timeout
+import os
+import time
+
+client = OpenAI(
+    base_url="https://hy3.example.com/v1",
+    api_key=os.getenv("HY3_API_KEY", "你的API_KEY"),
+    timeout=10  # 设置基础超时时间
+)
+
+# ========== 1. 基础异常捕获示例 ==========
+def basic_error_handle():
+    print("=== 基础异常捕获 ===")
+    try:
+        resp = client.chat.completions.create(
+            model="hy3-base",
+            messages=[{"role": "user", "content": "你好"}],
+            max_tokens=100
+        )
+        print("请求成功：", resp.choices[0].message.content[:30], "...")
+    except APIConnectionError:
+        print("错误：网络连接失败，请检查网络或接口地址")
+    except RateLimitError:
+        print("错误：触发限流，请稍后再试")
+    except Timeout:
+        print("错误：请求超时，请检查网络或增大timeout")
+    except APIError as e:
+        print(f"接口返回错误：{e}")
+    except Exception as e:
+        print(f"未知错误：{e}")
+    print()
+
+# ========== 2. 指数退避自动重试 ==========
+def request_with_retry(messages, max_retries=3, base_delay=1):
+    """带重试退避的请求函数"""
+    for retry in range(max_retries):
+        try:
+            resp = client.chat.completions.create(
+                model="hy3-base",
+                messages=messages,
+                max_tokens=200
+            )
+            return resp
+        except (RateLimitError, APIConnectionError, Timeout) as e:
+            if retry == max_retries - 1:
+                raise e
+            # 指数退避：第1次等1秒，第2次等2秒，第3次等4秒
+            delay = base_delay * (2 ** retry)
+            print(f"第 {retry+1} 次请求失败，{delay}秒后重试... 错误：{type(e).__name__}")
+            time.sleep(delay)
+
+def retry_demo():
+    print("=== 自动重试示例 ===")
+    messages = [{"role": "user", "content": "请介绍一下API重试机制的作用"}]
+    try:
+        resp = request_with_retry(messages, max_retries=3)
+        print("最终请求成功：", resp.choices[0].message.content[:50], "...")
+    except Exception as e:
+        print(f"重试全部失败，最终错误：{e}")
+    print()
+
+if __name__ == "__main__":
+    basic_error_handle()
+    retry_demo()
+    print("=== 常见错误说明 ===")
+    print("401 Unauthorized：API Key无效，请检查密钥")
+    print("429 Rate Limit：请求频率超限，建议增加重试间隔")
+    print("400 Bad Request：参数格式错误，请检查请求字段")
+    print("5xx 服务端错误：服务端异常，稍后重试即可")

examples/reasoning_switch.py

@@ -0,0 +1,50 @@
+from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="https://hy3.example.com/v1",
+    api_key=os.getenv("HY3_API_KEY", "你的API_KEY")
+)
+
+question = "有一个水池，单开甲管6小时注满，单开乙管4小时注满。两管同时开，几小时能注满水池？"
+
+# ========== 1. 关闭思考模式（直接出答案） ==========
+def reasoning_off():
+    print("=== 思考模式关闭 ===")
+    resp = client.chat.completions.create(
+        model="hy3-base",
+        messages=[{"role": "user", "content": question}],
+        max_tokens=300,
+        reasoning_mode=False
+    )
+    answer = resp.choices[0].message.content
+    print("回答：")
+    print(answer)
+    print()
+
+# ========== 2. 开启思考模式（展示推理过程） ==========
+def reasoning_on():
+    print("=== 思考模式开启 ===")
+    resp = client.chat.completions.create(
+        model="hy3-reason",
+        messages=[{"role": "user", "content": question}],
+        max_tokens=800,
+        reasoning_mode=True
+    )
+    message = resp.choices[0].message
+    # 思考过程与最终回答分离
+    reasoning_content = message.reasoning_content if hasattr(message, "reasoning_content") else "（无思考过程输出）"
+    final_answer = message.content
+
+    print("思考过程：")
+    print(reasoning_content)
+    print("\n最终答案：")
+    print(final_answer)
+    print()
+
+if __name__ == "__main__":
+    reasoning_off()
+    reasoning_on()
+    print("=== 对比总结 ===")
+    print("关闭思考：回答简洁、速度快，适合日常对话")
+    print("开启思考：输出完整推理步骤，准确率更高，适合数学、逻辑类复杂问题")

examples/stream_vs_normal.py

@@ -0,0 +1,63 @@
+from openai import OpenAI
+import os
+import time
+
+client = OpenAI(
+    base_url="https://hy3.example.com/v1",
+    api_key=os.getenv("HY3_API_KEY", "你的API_KEY")
+)
+
+prompt = "请用200字左右介绍人工智能的发展历程"
+
+# ========== 1. 非流式请求计时 ==========
+def test_non_streaming():
+    start_time = time.time()
+    resp = client.chat.completions.create(
+        model="hy3-base",
+        messages=[{"role": "user", "content": prompt}],
+        max_tokens=300,
+        stream=False
+    )
+    total_time = time.time() - start_time
+    content = resp.choices[0].message.content
+    print("=== 非流式模式 ===")
+    print(f"总耗时：{total_time:.2f} 秒")
+    print(f"回答开头：{content[:30]}...")
+    print()
+    return total_time
+
+# ========== 2. 流式请求计时（首token + 总耗时） ==========
+def test_streaming():
+    start_time = time.time()
+    first_token_time = None
+    full_content = ""
+
+    stream = client.chat.completions.create(
+        model="hy3-base",
+        messages=[{"role": "user", "content": prompt}],
+        max_tokens=300,
+        stream=True
+    )
+
+    for chunk in stream:
+        if chunk.choices and chunk.choices[0].delta.content:
+            if first_token_time is None:
+                first_token_time = time.time() - start_time
+            full_content += chunk.choices[0].delta.content
+
+    total_time = time.time() - start_time
+    print("=== 流式模式 ===")
+    print(f"首token时延：{first_token_time:.2f} 秒")
+    print(f"总耗时：{total_time:.2f} 秒")
+    print(f"回答开头：{full_content[:30]}...")
+    print()
+    return first_token_time, total_time
+
+if __name__ == "__main__":
+    non_stream_total = test_non_streaming()
+    first_token, stream_total = test_streaming()
+
+    print("=== 对比总结 ===")
+    print(f"非流式总耗时：{non_stream_total:.2f}s")
+    print(f"流式首token时延：{first_token:.2f}s（用户更快看到第一个字）")
+    print(f"流式总耗时：{stream_total:.2f}s")

examples/streaming_chat.py

@@ -0,0 +1,38 @@
+from openai import OpenAI
+import os
+
+client = OpenAI(
+    base_url="https://hy3.example.com/v1",
+    api_key=os.getenv("HY3_API_KEY", "你的API_KEY")
+)
+
+def streaming_chat_demo():
+    print("=== 流式逐块输出示例 ===")
+    print("用户：请简单介绍一下大语言模型的流式输出")
+    print("助手：", end="", flush=True)
+
+    # 开启流式请求 stream=True
+    stream = client.chat.completions.create(
+        model="hy3-base",
+        messages=[
+            {"role": "user", "content": "请简单介绍一下大语言模型的流式输出"}
+        ],
+        temperature=0.7,
+        max_tokens=300,
+        stream=True
+    )
+
+    full_answer = ""
+    # 逐 chunk 解析并打印
+    for chunk in stream:
+        if chunk.choices and chunk.choices[0].delta.content:
+            content = chunk.choices[0].delta.content
+            full_answer += content
+            print(content, end="", flush=True)
+
+    print("\n")
+    print("=== 完整拼接后的回答 ===")
+    print(full_answer)
+
+if __name__ == "__main__":
+    streaming_chat_demo()

examples/tool_calling.py

@@ -0,0 +1,108 @@
+from openai import OpenAI
+import os
+import json
+
+client = OpenAI(
+    base_url="https://hy3.example.com/v1",
+    api_key=os.getenv("HY3_API_KEY", "你的API_KEY")
+)
+
+# 定义工具函数：模拟查询天气
+def get_weather(city: str) -> str:
+    """模拟查询指定城市的天气"""
+    weather_data = {
+        "北京": "晴，25℃，风力2级",
+        "上海": "多云，28℃，风力3级",
+        "深圳": "阵雨，30℃，风力4级"
+    }
+    return weather_data.get(city, f"暂无{city}的天气数据")
+
+# 工具定义（传给模型的函数描述）
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "查询指定城市的实时天气",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "city": {
+                        "type": "string",
+                        "description": "城市名称，如北京、上海"
+                    }
+                },
+                "required": ["city"]
+            }
+        }
+    }
+]
+
+# ========== 1. 单次工具调用示例 ==========
+def single_tool_call():
+    print("=== 单次工具调用 ===")
+    messages = [{"role": "user", "content": "北京今天天气怎么样？"}]
+
+    resp = client.chat.completions.create(
+        model="hy3-base",
+        messages=messages,
+        tools=tools,
+        tool_choice="auto"
+    )
+
+    msg = resp.choices[0].message
+    # 解析模型返回的工具调用
+    if msg.tool_calls:
+        tool_call = msg.tool_calls[0]
+        func_name = tool_call.function.name
+        func_args = json.loads(tool_call.function.arguments)
+        print(f"模型调用工具：{func_name}，参数：{func_args}")
+
+        # 执行工具函数
+        result = get_weather(func_args["city"])
+        print(f"工具返回结果：{result}")
+    print()
+
+# ========== 2. 多轮工具循环完整流程 ==========
+def multi_turn_tool_loop():
+    print("=== 多轮工具循环完整流程 ===")
+    messages = [{"role": "user", "content": "帮我查一下上海的天气，然后用通俗的话总结一下"}]
+
+    # 第一轮：请求模型，触发工具调用
+    resp = client.chat.completions.create(
+        model="hy3-base",
+        messages=messages,
+        tools=tools,
+        tool_choice="auto"
+    )
+    msg = resp.choices[0].message
+    messages.append(msg)
+
+    # 执行所有工具调用并把结果回传给模型
+    if msg.tool_calls:
+        for tool_call in msg.tool_calls:
+            func_name = tool_call.function.name
+            func_args = json.loads(tool_call.function.arguments)
+            result = get_weather(func_args["city"])
+
+            # 把工具结果加入对话历史
+            messages.append({
+                "role": "tool",
+                "tool_call_id": tool_call.id,
+                "name": func_name,
+                "content": result
+            })
+
+    # 第二轮：模型基于工具结果生成最终回答
+    final_resp = client.chat.completions.create(
+        model="hy3-base",
+        messages=messages
+    )
+
+    final_answer = final_resp.choices[0].message.content
+    print("用户问题：帮我查一下上海的天气，然后用通俗的话总结一下")
+    print("模型最终回答：", final_answer)
+
+if __name__ == "__main__":
+    single_tool_call()
+    multi_turn_tool_loop()