# ============================================================
# 示例：用 OpenAI SDK 调用阿里云百炼（通义千问）大模型
# 整体流程：导入库 → 创建客户端 → 构造消息 → 发起请求 → 流式打印
# ============================================================

# from：Python 的「从…导入…」语法，从指定模块中引入需要的类/函数
# openai：OpenAI 官方 Python 包，提供统一的 chat.completions 调用方式
# OpenAI：包里的客户端类，用来连接大模型 API 并发送请求
from openai import OpenAI

# import os：导入 Python 标准库 os，用于读取操作系统环境变量
import os

# ------------------------------------------------------------------
# 第 1 步：创建 API 客户端（client = 客户端对象，后续所有请求都通过它发起）
# ------------------------------------------------------------------
client = OpenAI(
    # api_key：API 密钥，相当于「账号密码」，服务端凭此识别你的身份并计费
    # os.getenv("DASHSCOPE_API_KEY")：从系统环境变量中读取名为 DASHSCOPE_API_KEY 的值
    # 好处：密钥不写死在代码里，更安全；若未配置环境变量，此处返回 None
    # 备选写法（仅本地调试）：api_key="sk-你的百炼密钥"
    api_key=os.getenv("DASHSCOPE_API_KEY"),

    # # 不要直接把你的key写进代码，安全的方式是用环境变量保存
    # api_key = "123550090124",

    # base_url：API 服务的基础地址（根 URL）
    # 阿里云百炼提供「OpenAI 兼容模式」，所以可以用 OpenAI SDK 直接调用
    # /compatible-mode/v1 表示兼容 OpenAI v1 接口规范
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

# ------------------------------------------------------------------
# 第 2 步：构造对话消息（messages = 消息列表，模拟多轮对话）
# ------------------------------------------------------------------
# messages：列表（list），每个元素是一条消息，用字典（dict）表示
# role：角色，常见取值：
#   - "user"     → 用户说的话
#   - "assistant"→ 模型之前的回复（多轮对话时带上，模型才能「记住」上下文）
#   - "system"   → 系统提示词，用来设定模型的人设、规则、输出格式等
# content：该条消息的具体文本内容
messages = [{"role": "user", "content": "你是谁"}]

# ------------------------------------------------------------------
# 第 3 步：发起聊天补全请求（completion = 补全/生成结果）
# client.chat.completions.create(...)：OpenAI SDK 的标准聊天接口
# ------------------------------------------------------------------
completion = client.chat.completions.create(
    # model：指定要调用的模型名称，不同模型能力、价格、速度不同
    model="qwen3.6-flash",

    # messages：传入上面构造好的对话历史，模型会根据这些内容生成回复
    messages=messages,

    # extra_body：额外请求体参数，会原样附加到 HTTP 请求 JSON 中
    # enable_thinking: True → 开启「深度思考」模式，模型会先输出思考过程再给出最终答案
    # 思考内容在流式响应里通过 reasoning_content 字段返回（见下方循环）
    extra_body={"enable_thinking": True},

    # stream=True：开启流式输出（Streaming）
    # True 表示不一次性返回完整结果，而是像打字一样逐块（chunk）推送
    # 好处：用户能更快看到首字，体验更流畅；适合长回复场景
    stream=True
)

# ------------------------------------------------------------------
# 第 4 步：逐块读取流式响应并打印
# ------------------------------------------------------------------

# is_answering：布尔标志（False/True），用来区分当前处于哪个输出阶段
# False → 还在输出「思考过程」；True → 已进入「正式回复」阶段
is_answering = False

# print：向控制台输出文字
# "\n"：换行符； "=" * 20：把 "=" 重复 20 次，用作分隔线，让输出更易读
print("\n" + "=" * 20 + "思考过程" + "=" * 20)

# for chunk in completion：遍历流式返回的每一个数据块
# chunk：单次推送的一小段 JSON 数据，可能只含几个 token（字/词片段）
for chunk in completion:

    # 流式结束时，服务端可能发送一个 choices 为空的 chunk（例如只含 token 用量统计）
    # 若直接访问 chunk.choices[0] 会报 IndexError，因此先判断是否为空
    # not chunk.choices：列表为空时条件为 True
    # continue：跳过本次循环，直接进入下一个 chunk
    if not chunk.choices:
        continue

    # chunk.choices：候选回复列表，通常只有 1 个元素（索引 0）
    # .delta：本次 chunk 相对于上一次的「增量变化」，不是完整内容，而是新增片段
    delta = chunk.choices[0].delta

    # ---------- 处理「思考过程」片段 ----------
    # hasattr(obj, "attr")：检查对象 obj 是否有名为 attr 的属性（防止旧版 SDK 无此字段报错）
    # delta.reasoning_content：深度思考模式下，模型内部推理过程的文本片段
    # is not None：排除字段存在但值为 None 的情况
    if hasattr(delta, "reasoning_content") and delta.reasoning_content is not None:
        # 只有还没进入正式回复阶段时，才打印思考内容
        if not is_answering:
            # end=""：打印后不自动换行，让多个 chunk 的内容拼接成一行/一段
            # flush=True：立刻刷新输出缓冲区，确保文字实时显示（不等缓冲区满）
            print(delta.reasoning_content, end="", flush=True)

    # ---------- 处理「正式回复」片段 ----------
    # delta.content：模型最终回复正文的增量片段
    # and delta.content：同时排除空字符串，避免打印无意义空内容
    if hasattr(delta, "content") and delta.content:
        # 第一次收到正式回复时，打印分隔标题并切换阶段标志
        if not is_answering:
            print("\n" + "=" * 20 + "完整回复" + "=" * 20)
            is_answering = True  # 标记：此后不再打印思考内容
        print(delta.content, end="", flush=True)

# 循环结束后程序正常退出，无额外代码