🔌 语言模型抽象

class BaseLanguageModel(
    RunnableSerializable[LanguageModelInput, LanguageModelOutputVar], ABC
):
    """所有语言模型的抽象基类。"""

    cache: BaseCache | bool | None = Field(default=None)
    """是否缓存响应（避免重复调用浪费 token）"""

    verbose: bool = Field(default_factory=_get_verbosity)
    """是否打印响应文本（调试用）"""

    callbacks: Callbacks = Field(default=None)
    """回调（追踪、流式、可观测）"""

    tags: list[str] | None = Field(default=None)
    metadata: dict[Any, Any] | None = Field(default=None)
    """给运行追踪打标签 / 元数据"""

    custom_get_token_ids: Callable[[str], list[int]] | None = None
    """自定义 tokenizer，用于精确计 token"""

class BaseChatModel(BaseLanguageModel):

    def bind_tools(
        self,
        tools: Sequence[dict | type | Callable | BaseTool],
        *,
        tool_choice: str | None = None,
        **kwargs: Any,
    ) -> Runnable[LanguageModelInput, AIMessage]:
        """把工具绑定到模型。

        Args:
            tools: 工具序列。可以是 dict(JSON Schema) / type(Pydantic) /
                   Callable(普通函数) / BaseTool 对象。LC6 会讲怎么定义工具。
            tool_choice: 强制选择。
                None = 模型自己决定；"any" = 必须调一个工具；
                具体工具名 = 强制调那个工具。

        Returns:
            一个新的 Runnable —— 调用时模型已"知道"这些工具的存在，
            输出的 AIMessage 会带 tool_calls。
        """
        raise NotImplementedError   # 子类（如 ChatOpenAI）具体实现

class BaseChatModel(BaseLanguageModel):

    def with_structured_output(
        self,
        schema: dict | type,
        *,
        include_raw: bool = False,
        **kwargs: Any,
    ) -> Runnable[LanguageModelInput, dict | BaseModel]:
        """让模型按给定 schema 输出结构化数据。

        schema 可以是: OpenAI 工具 schema / JSON Schema / Pydantic 类。
        返回的 Runnable 直接输出 dict 或 Pydantic 对象，省去手动解析。
        """
        ...

# pip install langchain langchain-openai
# export OPENAI_API_KEY="sk-..."
import os
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from pydantic import BaseModel

model = ChatOpenAI(model="gpt-4o-mini")

# ============ ① 三种调用方式 ============
# invoke：单次同步
resp = model.invoke([HumanMessage(content="用一句话介绍Python")])
print("invoke:", resp.content)

# stream：流式（逐字返回 AIMessageChunk）
print("stream: ", end="")
for chunk in model.stream([HumanMessage(content="数到5")]):
    print(chunk.content, end="", flush=True)
print()

# batch：并发处理多个输入
results = model.batch(["1+1=?", "2+2=?"])
print("batch:", [r.content for r in results])


# ============ ② bind_tools（工具调用） ============
# 这里用 dict 形式的工具 schema（LC6 会学 @tool 装饰器更优雅）
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询城市天气",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

model_with_tools = model.bind_tools(tools)
ai_msg = model_with_tools.invoke("北京天气如何？")
print("tool_calls:", ai_msg.tool_calls)
# → [{'name': 'get_weather', 'args': {'city': '北京'}, 'id': 'call_xxx'}]
# 注意 content 可能为空 —— 模型选择调工具而非直接回答


# ============ ③ with_structured_output（结构化输出） ============
class PersonInfo(BaseModel):
    name: str
    age: int
    hobby: str

structured_model = model.with_structured_output(PersonInfo)
person = structured_model.invoke("张三今年25岁，喜欢打篮球。提取信息。")
print("structured:", person)  # → PersonInfo(name='张三', age=25, hobby='打篮球')
print("type:", type(person))  # → <class 'PersonInfo'>  直接拿到 Pydantic 对象！