# Talkie 1930 聊天适配器与提示词教学素材

这组程序把本地 Talkie 1930 模型接成可连续聊天的工具：用户输入经过角色标记和分词，拼接到历史上下文，再逐 token 生成 assistant 回复。它适合用来讲解 system、user、assistant 三种消息角色，以及聊天界面背后的真实输入序列。

原目录：`/home/wangyi/code/0 prev/talkie1930/`。归档日期：2026-10-11。文件来源、哈希和归档修改见 [provenance.json](provenance.json)。

## 当时做了什么

| 文件 | 功能 |
| --- | --- |
| [chat.py](chat.py) | 命令行单轮测试，原始问题是请模型写一封婉拒晚宴邀请的短信 |
| [chatgui.py](chatgui.py) | tkinter 多轮聊天窗口，后台线程生成，GPU tensor 保存完整对话历史 |
| [chatweb.py](chatweb.py) | Flask 网页聊天，内嵌 HTML／CSS／JS，通过 SSE 流式显示输出，支持停止生成、清空历史和访问口令 |
| [reference/talkie_qmodel.py](reference/talkie_qmodel.py) | 从模型缓存归档的上游 GPTQModel 架构 adapter：注册 TalkieQModel，声明注意力和 MLP 模块的量化分组 |
| [reference/tokenizer.py](reference/tokenizer.py) | 原环境安装的 Talkie 分词器代码，定义聊天特殊 token 及其 ID |

三个聊天脚本加载 `dtestnyrr/talkie-1930-13b-it-gptq-int4`，使用 `GPTQ_TRITON` 后端，并从 `talkie-lm/talkie-1930-13b-it` 取得 `vocab.txt`。原作者的工作在聊天接口、消息拼接、多轮状态及解码流程；缓存中的 `TalkieQModel` 是模型发布方提供的架构适配代码。

生成循环直接调用 `model.model(input_ids=ids)`，每一步重新输入完整序列，再按温度采样一个 token。`chat.py` 的注释说明，这样处理是为绕过当时 Transformers 5.x 缓存解码只送入最后一个 token 的兼容问题。开头若干步屏蔽停止 token，代码注释将其用于缓解 4-bit 量化后的过早停止。

| 参数 | 命令行 | 桌面窗口 | 网页 |
| --- | --- | --- | --- |
| temperature | 0.7 | 0.7 | 0.5 |
| 开头屏蔽停止 token 的步数 | 50 | 50 | 5 |
| 最大新 token 数 | 5000 | 400 | 50000 |

网页用锁串行执行生成，历史统一保存在 `"default"` 下；访问者共享这一段上下文。原代码没有上下文截断，长对话会持续增加每步计算量。

## 1930 年代设定来自模型训练

Talkie 官方模型卡说明：基础模型为 13B 参数，使用 260B token 的 1931 年以前英文文本训练；指令微调样本来自同一时期的礼仪手册、百科全书和书信指南等，之后进行 online DPO。[官方模型卡](https://huggingface.co/talkie-lm/talkie-1930-13b-it)

因此这个案例可以先区分两种影响：训练材料形成模型已有的语言与知识倾向；当前对话的提示词提供本轮任务、规则和上下文。原聊天代码直接调用这一模型，未额外添加“扮演 1930 年代人物”的 system 文案。

## 三种消息角色怎样进入模型

| 角色或标记 | 教学含义 | 本程序中的实际状态 |
| --- | --- | --- |
| system | 对话的整体规则或背景设定 | 分词器支持 `<\|system\|>`；三个聊天脚本没有插入 system 消息 |
| user | 用户这一轮的问题或任务 | 在用户输入前插入 `<\|user\|>`，末尾加 `<\|end\|>` |
| assistant | 助手已有的回复，或即将生成回复的角色 | 输入末尾加 `<\|assistant\|>`；生成的回复保留进历史，结束后追加 `<\|end\|>` |

关键代码在 `chatgui.py` 的 `_generate_in_background` 和 `chatweb.py` 的 `api_chat`：

```python
turn_ids = tokenizer.encode(
    f"<|user|>{user_text}<|end|><|assistant|>",
    allowed_special="all",
)
```

这里的 assistant 部分可以讲成“告诉模型从助手位置继续写”。角色标记后面已有的文字也可作为续写开头，即 assistant prefill；先前的 assistant 回复则是后续请求的一部分上下文。原界面仅提供用户输入框，尚未提供 system 编辑器或 assistant prefill 编辑器。

桌面窗口中的 `_append_system("Loading model…")` 只向界面写状态提示，没有把文字加入模型输入。讲解时可用它说明“界面标注为系统消息”和“实际发送 system 角色消息”的区别。

本 tokenizer 将 `<|endoftext|>`、`<|end|>`、`<|user|>`、`<|assistant|>`、`<|system|>` 分别映射为 65535、65536、65537、65538、65539。它们作为特殊 token 被编码。原程序使用 `allowed_special="all"`，用户输入中的这些字面标记也会被当作特殊 token，可作为讲解角色边界处理的代码例子。

## 课堂可用的输入序列

原单轮输入，来自 `chat.py`：

```text
<|user|>Write a brief letter declining a dinner invitation.<|end|><|assistant|>
```

多轮结构如下；方括号文字表示对应内容的位置：

```text
<|user|>[第一轮问题]<|end|><|assistant|>[第一轮回复]<|end|><|user|>[追问]<|end|><|assistant|>
```

下面是为课堂新增的 system 与 assistant prefill 示例。可以展示序列，或在后续扩展界面时把各段设为可编辑；当前归档不包含这些问题的模型输出：

```text
<|system|>You are a courteous letter-writing adviser. Keep replies brief.<|end|><|user|>Write a brief letter declining a dinner invitation.<|end|><|assistant|>Dear Mrs. Brown,
```

讲解顺序：先固定 user 问题观察模型；再添加 system 规则；最后给 assistant 一个开头，观察续写位置如何变化。三段的可单独复制版本见 [prompt_examples.json](prompt_examples.json)。

## 运行环境与归档处理

原目录指定 Python 3.13。归档时读取原 `.venv` 的包元数据得到：PyTorch 2.11.0、Transformers 5.7.0、GPTQModel 7.0.0、huggingface_hub 1.12.2、Flask 3.1.3、talkie 0.1.0、tiktoken 0.12.0。这是原环境快照；CUDA、Triton 及模型权重仍由运行环境提供。

脚本保留原本机模型缓存路径，snapshot 为 `79636b378d6475423cd68a5213c47eb781673ac2`。本目录保存代码和参考说明，不含模型权重、词表及 `.venv`。`reference/` 的代码用于讲解来源，原脚本仍从模型缓存和安装包导入依赖。

`chat.py`、`chatgui.py` 和参考文件按原字节保存。`chatweb.py` 归档时将硬编码口令改为环境变量 `TALKIE_ACCESS_KEY`，将注释和启动提示中的原主机地址换为 `127.0.0.1`；其他逻辑保留。启动网页前设置该环境变量，再用配齐上述依赖的 Python 执行 `chatweb.py`。服务端口为 5000，原配置监听 `0.0.0.0`。

归档验证覆盖 Python 语法、文件哈希、消息模板和特殊 token 映射；本次未加载 GPU 模型或启动聊天服务。原目录尚无 Git 提交，因此使用文件哈希标识此次快照。

## 来源

- 用户代码：`/home/wangyi/code/0 prev/talkie1930/`。
- [Talkie 官方模型卡](https://huggingface.co/talkie-lm/talkie-1930-13b-it)与[官方代码](https://github.com/talkie-lm/talkie)。
- [GPTQ INT4 模型仓库](https://huggingface.co/dtestnyrr/talkie-1930-13b-it-gptq-int4)，本地缓存模型卡保存在 [reference/quantized_model_card.md](reference/quantized_model_card.md)，许可证标注为 Apache 2.0。