从 TGI 旧版本升级到 3.x，最大的变化之一是把启动参数收敛到配置文件，自定义 tokenizer 的很多旧写法会直接失效。迁移不要从“感觉能跑”出发，而要从“旧配置到底有哪些字段、新版配置加载到哪里”出发。建议先把当前启动命令和模型目录里的 tokenizer_config.json 完整备份，再逐步替换。
升级 TGI 3.x 前，先冻结旧启动命令和 tokenizer_config.json；迁移时把自定义 tokenizer 配置从 CLI/env 参数移入新版 config 文件，并以加载日志和 tokenization 输出为验证依据。不要假设旧参数还能用，尤其是通过环境变量覆盖的自定义配置。
先判断你的自定义 tokenizer 配置属于哪一类
按配置来源和效果，通常分为三类：tokenizer 路径、special token 修改、预处理参数。下面给出核对维度，字段名以你安装版本的 `--help` 输出为准。
| 配置类型 | 旧版常见位置 | 迁移动作 |
|---|---|---|
| tokenizer 路径/名称 | 启动命令里的 `--tokenizer` 或环境变量 | 放入 config 文件对应的 tokenizer 节点，尽量使用绝对路径 |
| special token 或附加 token | 模型目录中的 tokenizer_config.json，或启动参数覆盖 | 保留模型目录 JSON 为主，config 文件只写覆盖项 |
| trust_remote_code 与预处理参数 | CLI flag 或 env 变量 | 在新版 config 的对应字段显式声明，避免靠默认值猜 |
迁移操作顺序
按以下顺序操作，可以降低漏项风险：
- 记录旧启动命令：保存当前服务启动脚本或 docker run 命令，特别是所有 tokenizer 相关参数。
- 备份模型目录内的 tokenizer 相关文件：包括 tokenizer_config.json、tokenizer.json、special_tokens_map.json、vocab.txt 或 sentencepiece model。
- 用新版服务生成默认 config 文件：通常可以通过 `--help` 或 `--config-file` 参数获得默认结构。
- 把旧参数映射到新 config，写完后先本地启动，不直接上生产。
# config.yaml 示意图，字段名以实际版本的 `--help` 输出为准
model: /data/models/your-model
tokenizer:
path: /data/models/your-model
trust_remote_code: true
# 如果你需要覆盖特殊 token，写在这里
special_tokens:
additional_special_tokens: ["<extra0>", "<extra1>"]如果你的旧配置里有通过环境变量动态拼 tokenizer_config 的逻辑，这在新版里往往是最先失效的。建议不要在 config 文件里做字符串拼接，直接把完整 JSON 内容写在模型目录里，新版服务读取时更稳定。
验证配置是否真的生效
升级后不能只看服务能启动，还要确认 tokenizer 确实加载了你的配置。按下面清单核验：
- 启动日志中 tokenizer 的加载路径是否是你的模型目录或自定义路径。
- 用同一个输入文本，对比升级前后 encode 得到的 token id 序列，尤其看 special token 是否保留。
- 如果新版服务暴露了 /tokenize 接口，可以用请求直接检查；不确定时先用普通生成请求对比输出。
curl -s 'http://127.0.0.1:8080/tokenize' -H 'Content-Type: application/json' -d '{"inputs": "<extra0> 你好"}'返回内容里如果与旧版 token id 序列一致，说明迁移成功；如果不一致，优先检查 config 文件是否被服务加载，以及启动日志里有没有忽略旧参数的 warning。
常见问题
旧启动命令里的 `--tokenizer` 参数还能用吗？
在新版 TGI 上仍然可能有兼容写法，但自定义配置建议都迁移到 config 文件。用 `--help` 确认这个参数是否还在，如果不在就不要再保留。
迁移后自定义 tokenizer 不生效，怎么定位？
先确认服务启动时加载的是你写的 config 文件，而不是默认参数；再看启动日志有没有 tokenizer 相关的 warning；最后用 /tokenize 或生成接口做 token 级对比。