企业官网建设流程全解析

• 大模型
• AI 应用
• 后端

TypeChat 的 Restaurant 示例（python/examples/restaurant）演示了如何把一段充满"复合句、干扰信息和修正表达"的自然语言点餐请求，翻译成严格校验过的 JSON 订单对象，并进一步生成一份不依赖大语言模型的"用户意图摘要"用于人工确认。读完本文，你将掌握该示例的完整运行方式、Order类型 Schema 的设计思路、TypeChat 的"翻译—校验—修复"闭环原理，以及"意图摘要必须脱离 LLM 生成"这一关键工程实践。

一、示例定位：以"名词"承载更复杂的语言输入

Restaurant 示例与 Coffee Shop 示例（python/examples/coffeeShop）一样，属于"把用户意图捕获为一组名词（订单条目）"的类型，但它的输入语言复杂度明显更高：句子中包含多个并列的订单条目、对已有条目的追加修正（如"把其中一个香肠披萨做成小份"）、与订单无关的干扰句（闲聊），以及口语化的别名（如"M&J"指代 Mack and Jacks）。

正如 README 所述，这个示例天然充当"语言模型的压力测试"：它清晰地区分出较简单的模型与更先进的模型在解析复合句、剔除干扰、理解修正这三类语言现象时的能力差异。示例同时展示了如何生成一份"用户意图摘要"回显给用户确认。

二、快速运行 Restaurant 示例

运行该示例需要 Python 3.11+ 与 hatch，或直接使用 venv + pip，具体环境搭建步骤见 python/examples/README.md。环境准备好后：

# 进入 python 目录 hatch shell # 或使用 venv： # python -m venv ../.venv && source ../.venv/bin/activate && pip install .[examples] # 在 restaurant 目录下交互式运行 python examples/restaurant/demo.py

示例支持两种输入方式，入口逻辑都在 demo.py 中：

• 交互模式：直接运行python examples/restaurant/demo.py，程序以🍕>为提示符等待输入，输入quit或exit结束会话；
• 文件模式：python examples/restaurant/demo.py input.txt，逐行读取 input.txt 中的 13 条测试文本（以#开头的行会被跳过）。

上述两种模式由 process_requests 统一实现，它把每一行文本回调给request_handler。文件模式下 demo.py 对每条请求先打印翻译出的 JSON，再检查是否存在itemType == "Unknown"的条目并回显无法理解的内容。

环境变量配置

示例通过 OpenAI 或 Azure OpenAI 端点调用模型，需要预先配置环境变量（建议写入项目根目录的.env文件）：

demo.py 使用dotenv_values()读取环境变量，再交给 create_language_model 构造模型封装；该函数按OPENAI_API_KEY/AZURE_OPENAI_API_KEY是否存在自动选择端点，缺少关键变量时会直接抛出异常。底层 HttpxLanguageModel 统一以temperature: 0.0、n: 1请求模型，并对 429/500/502/503/504 等瞬时错误自动重试最多 3 次，默认超时 10 秒。

三、点餐 Schema：用 TypedDict 描述"名词"世界

订单的类型定义在 schema.py 中，是整个示例的核心。它由Order、OrderItem联合类型、Pizza、Beer、Salad与兜底的UnknownText组成：

OrderItem = Pizza | Beer | Salad class Order(TypedDict): items: list[OrderItem | UnknownText]

要点如下：

• 判别字段itemType：Pizza、Beer、Salad各自用Literal["Pizza"]等作为类型判别，翻译出的 JSON 依据该字段区分订单条目类型；
• UnknownText兜底：凡是模型无法归入任何已知类型的文本，都会被放入itemType: Literal["Unknown"]的条目，原文保留在text字段中，供程序向用户回显"我没理解的部分"；
• 可选字段与默认值：Pizza与Salad使用total=False声明为"部分字段可选"，并通过Annotated元数据向模型传达默认值，如披萨size默认large、quantity默认1，沙拉portion默认half、style默认Garden；
• 名词枚举：披萨name限定为"Hawaiian"、"Yeti"、"Pig In a Forest"、"Cherry Bomb"四种，啤酒kind给出"Mack and Jacks"、Sierra Nevada Pale Ale、Miller Lite等示例，这些枚举直接约束了模型输出的取值空间。

这些 Python 类型在 TypeChatJsonTranslator 初始化时，由python_type_to_typescript_schema（实现见 python_type_to_ts_nodes.py）转换成一份 TypeScript 类型声明字符串，作为 Prompt 的主体注入给模型。TypedDict、Literal、Annotated（含Doc说明）等标注都会被忠实映射为对应的 TS 接口、字面量联合类型与注释。

四、输入输出对照：从复合句到结构化订单

示例输入文件 input.txt 里包含了多条高难度语句。README 以其中第 4 条为例：

Input：

🍕> I want three pizzas, one with mushrooms and the other two with sausage. Make one sausage a small. And give me a whole Greek and a Pale Ale. And give me a Mack and Jacks.

Output（GPT-4-0613）：

1 large pizza with mushrooms 1 large pizza with sausage 1 small pizza with sausage 1 whole Greek salad 1 Pale Ale 1 Mack and Jacks

注意这里订单总数始终是3 份披萨：1 份蘑菇 + 1 份香肠大份 + 1 份香肠小份。"Make one sausage a small"（把其中一份香肠改成小份）是对既有条目的修正，而非新增一份披萨。模型需要理解这种跨句的指代与修改关系。

不同模型的分水岭

README 特别标注了该输入是 GPT-3.5-turbo 及大多数其他模型的失分点，典型的错误输出如下：

1 large pizza with mushrooms - 1 large pizza with sausage + 2 large pizza with sausage 1 small pizza with sausage 1 whole Greek salad 1 Pale Ale 1 Mack and Jacks

GPT-3.5-turbo 会错误地把"把一份香肠改成小份"理解成"再加两份香肠大披萨"，从而得出 1 份蘑菇 + 3 份香肠的错误结论。这直观说明：面对复合句、干扰句与修正表达时，不同语言模型的推理能力存在显著差异，这也是本示例被设计为"模型压力测试"的原因。

input.txt 中还有大量同类高难度样本，例如第 6 条混入了与点餐无关的闲聊（"Lovely weather we're having"、"Boy, those Mariners are doggin it"），第 10 条要求"给其中两份加 extra sauce"，都要求模型先剔除干扰、再对子集条目做条件修饰。

五、意图摘要：确认环节必须绕开语言模型

示例 README 强调了一个重要工程原则：因为所有语言模型都是概率性的，偶尔会输出错误的推断，TypeChat 模式要求向用户请求确认（或提供便捷的撤销方式），并且确认环节绝不能依赖语言模型，否则错误推断会被一并写入意图摘要。

在 TypeScript 版示例中，摘要函数是 main.ts 里的printOrder(order: Order)。它不调用任何模型，纯粹对校验过的强类型订单对象做格式化输出：

function printOrder(order: Order) {

它之所以能放心地假设order的形态，是因为 TypeChat 的校验流程已经保证模型吐出的 JSON 与Order类型一致。这份摘要的具体处理逻辑包括：

• 按itemType分派到 pizza / beer / salad 三种渲染分支；
• 对披萨按namedPizzas表展开命名披萨的默认配料，并调用removeCommonStrings抵消同时出现在"添加"与"移除"列表中的配料（main.ts）；
• 未指定时补充默认值：披萨large、沙拉half/Garden；
• 当配料不在合法清单中时打印We are out of ${...}提示缺料。

在 Python 版 demo.py 中，翻译成功后会先打印json.dumps(result, indent=2)的结构化 JSON，再对Unknown条目逐条回显原文——同样不经过模型。两者的共同点是：面向用户回显的内容，一律来自已校验的数据，而不是模型的原始输出。

强类型数据的价值

之所以能"安全地"生成摘要，是因为翻译流水线保证了数据可信。以 Python 实现为例，核心链路在 translator.py 的translate方法中：

1. 构造请求 Prompt，把 TypeScript Schema 声明与用户意图一起发给模型（_create_request_prompt，translator.py）；
2. 从模型输出中截取首尾花括号之间的 JSON 片段，用pydantic_core.from_json解析；
3. 交给 TypeChatValidator.validate_object，后者通过pydantic.TypeAdapter(...).validate_json(..., strict=True)做严格校验；
4. 校验失败时，把包含"Validation path、失败值与原因"的诊断信息（_handle_error，validator.py）拼入修复 Prompt（_create_repair_prompt，translator.py），最多再重试_max_repair_attempts = 1次（translator.py）；
5. 最终返回Success[T]或携带错误信息的Failure（result.py）。

正是这层"翻译—校验—修复"闭环，让下游代码拿到的一定是满足Order约束的结构化数据，意图摘要才有资格完全脱离模型生成。

六、小结

Restaurant 示例展示了 TypeChat 在"名词型意图捕获"方向上的进阶形态：以TypedDict+Literal+Annotated定义订单 Schema，把复合句、修正表达与干扰句统统翻译为严格校验过的 JSON，再用纯代码生成用户可见的意图摘要用于确认。它既是检验语言模型理解能力的压力测试，也是"模型只负责推断、校验与回显交给确定性代码"这一 TypeChat 核心模式的完整范本。

进一步阅读建议：

• Schema 定义：python/examples/restaurant/schema.py
• 运行入口：python/examples/restaurant/demo.py
• 测试语料：python/examples/restaurant/input.txt
• TypeScript 版摘要实现：typescript/examples/restaurant/src/main.ts
• 翻译与校验内核：python/src/typechat/_internal/translator.py、python/src/typechat/_internal/validator.py
• 全部示例的环境配置与运行说明：python/examples/README.md

• 大模型
• AI 应用
• 后端