LangChain 学习第 1 课 - 模型基本调用

本节课学到：

1. ChatModel（聊天模型）是 LangChain 最核心的抽象，与具体厂商无关；
2. 模型的三种调用方式：invoke（单次）、stream（流式）、batch（批量）；
3. 消息（Message）的四种角色：System / Human / AI / Tool；
4. 返回结果 AIMessage 的结构（内容、token 用量等）。

"""
01 模型基本调用 —— LangChain 学习第 1 课
==========================================

本节课你会学到：
  1. ChatModel（聊天模型）是 LangChain 最核心的抽象，与具体厂商无关；
  2. 模型的三种调用方式：invoke（单次）、stream（流式）、batch（批量）；
  3. 消息（Message）的四种角色：System / Human / AI / Tool；
  4. 返回结果 AIMessage 的结构（内容、token 用量等）。

运行方式（在项目根目录下）：
    .venv\\Scripts\\python examples\\01_quickstart.py
"""

import sys
from pathlib import Path

# 让脚本可以独立运行：把项目根目录加入模块搜索路径，才能找到 config
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from langchain_core.messages import AIMessage, HumanMessage, SystemMessage  # 消息类型

from config import get_chat_model, print_sub, print_title  # 全局配置/排版工具


def demo_invoke_string() -> None:
    """方式一：最简单的字符串调用。传字符串会被自动包装成 HumanMessage。"""
    print_sub("1. invoke：最简单的单次调用（字符串输入）")
    llm = get_chat_model(temperature=0.3)  # temperature 低一些，回答更确定
    response: AIMessage = llm.invoke("用一句话向初学者解释什么是 LangChain")
    print("回答内容 response.content：")
    print(response.content)
    # response_metadata 里有厂商返回的原始信息（模型名、完成原因等）
    print(f"\nresponse_metadata：{response.response_metadata}")


def demo_invoke_messages() -> None:
    """方式二：消息列表调用 —— 真实应用最常用的姿势。"""
    print_sub("2. invoke：消息列表调用（System + Human）")
    llm = get_chat_model(temperature=0.7)

    # SystemMessage：设定 AI 的"人设"和规则（用户看不到）
    # HumanMessage：用户说的话
    messages = [
        SystemMessage(content="你是一个毒舌但善良的编程教练，说话简短，爱用比喻。"),
        HumanMessage(content="我学了三天 Python 还搞不懂递归，怎么办？"),
    ]
    response = llm.invoke(messages)
    print(response.content)

    # usage_metadata 记录 token 消耗（费用和上下文长度都靠它估算）
    print(f"\n本次 token 用量 usage_metadata：{response.usage_metadata}")


def demo_stream() -> None:
    """方式三：流式输出 —— 像 ChatGPT 网页版一样一个字一个字往外蹦。"""
    print_sub("3. stream：流式输出（逐块打印）")
    llm = get_chat_model(temperature=0.8)
    print("AI：", end="", flush=True)  # flush=True 立即刷新缓冲区，否则会卡成一坨
    # stream() 返回一个迭代器，每个 chunk 是一个小的 AIMessage 片段
    for chunk in llm.stream("用三句话鼓励一个刚开始学编程的人"):
        print(chunk.content, end="", flush=True)
    print()  # 换行收尾


def demo_batch() -> None:
    """方式四：批量调用 —— 一次提交多个独立问题，并发执行、按序返回。"""
    print_sub("4. batch：批量调用（多个问题并发）")
    llm = get_chat_model(temperature=0.0)  # 事实性任务用 0，减少随机发挥
    questions = [
        "中国的首都是哪里？只回答城市名。",
        "日本的首都是哪里？只回答城市名。",
        "法国的首都是哪里？只回答城市名。",
    ]
    responses = llm.batch(questions)  # 内部并发，结果顺序与输入顺序一致
    for q, r in zip(questions, responses):
        print(f"问：{q}\n答：{r.content.strip()}")


def main() -> None:
    print_title("01 模型基本调用：invoke / stream / batch 与消息类型")
    demo_invoke_string()
    demo_invoke_messages()
    demo_stream()
    demo_batch()
    print_sub("本课小结")
    print("ChatModel 三大调用：invoke（单次）、stream（流式）、batch（批量）。")
    print("消息四角色：SystemMessage 定人设、HumanMessage 是用户、AIMessage 是回答、ToolMessage 第 7 课见。")
    print("模型对象是无状态的：它不会记住上一句，多轮记忆请见 05_memory.py。")


if __name__ == "__main__":
    main()