LLM on XEDCZQ的博客

Ai面试项目：llm-provider模块

Tue, 09 Jun 2026 00:00:00 +0800

Llm-provider 模块设计与实现

这篇笔记记录 interview-guide 项目中 llm-provider 模块的设计与接口实现。该模块负责统一管理大模型 Provider 配置，包括模型列表、默认模型、Embedding 能力、连通性测试，以及语音面试中 ASR/TTS 的运行时配置。

模块能力概览

Provider 管理：支持查询、创建、更新、删除大模型 Provider。
双存储模式：兼容 DB 模式和 Legacy 配置文件模式。
密钥保护：DB 模式下 API Key 使用 AES-GCM 加密存储，接口返回前统一脱敏。
默认模型管理：区分默认 Chat Provider 和默认 Embedding Provider。
缓存重载：Provider 变更后清空 ChatClient 和 EmbeddingModel 缓存，下次调用时重新构建。
Embedding 校验：创建、更新和设置默认 Embedding Provider 时校验模型类型、维度和能力开关。
连通性测试：支持对 LLM Provider 发起真实 HTTP 测试请求。
语音配置管理：支持读取和更新 Qwen ASR/TTS 配置，并同步重载运行时服务。

流程图

stateDiagram-v2
 [*] --> ProviderConfigPage: 进入 LLM Provider 配置页

 ProviderConfigPage --> ProviderListLoaded: GET /api/llm-provider/list
 ProviderListLoaded --> ProviderDetailLoaded: GET /api/llm-provider/{id}

 ProviderListLoaded --> CreatingProvider: POST /api/llm-provider
 CreatingProvider --> ProviderSaved: 校验通过并保存
 CreatingProvider --> Error: id重复 / 参数非法 / 写入失败

 ProviderDetailLoaded --> UpdatingProvider: PUT /api/llm-provider/{id}
 UpdatingProvider --> ProviderSaved: 局部字段更新成功
 UpdatingProvider --> Error: Provider不存在 / 参数非法 / 写入失败

 ProviderSaved --> RegistryReloaded: registry.reload()
 RegistryReloaded --> ProviderListLoaded: 重新加载列表

 ProviderDetailLoaded --> TestingProvider: POST /api/llm-provider/{id}/test
 TestingProvider --> TestSuccess: 外部 LLM API 连接成功
 TestingProvider --> TestFailed: 连接失败 / 鉴权失败 / 模型不可用
 TestSuccess --> ProviderDetailLoaded
 TestFailed --> ProviderDetailLoaded

 ProviderDetailLoaded --> UpdatingDefaultChat: PUT /api/llm-provider/default-provider
 UpdatingDefaultChat --> DefaultChatUpdated: Provider存在
 UpdatingDefaultChat --> Error: Provider不存在 / defaultProvider为空

 ProviderDetailLoaded --> UpdatingDefaultEmbedding: PUT /api/llm-provider/default-embedding-provider
 UpdatingDefaultEmbedding --> DefaultEmbeddingUpdated: 支持 Embedding
 UpdatingDefaultEmbedding --> Error: Provider不存在 / 不支持Embedding

 DefaultChatUpdated --> RegistryReloaded
 DefaultEmbeddingUpdated --> RegistryReloaded

 ProviderDetailLoaded --> DeletingProvider: DELETE /api/llm-provider/{id}
 DeletingProvider --> ProviderDeleted: 非默认Provider
 DeletingProvider --> Error: Provider不存在 / 默认Provider不可删除
 ProviderDeleted --> RegistryReloaded

 ProviderListLoaded --> ManualReloading: POST /api/llm-provider/reload
 ManualReloading --> RegistryReloaded

 ProviderConfigPage --> VoiceConfigLoaded: GET /voice/asr 或 GET /voice/tts
 VoiceConfigLoaded --> UpdatingVoiceConfig: PUT /voice/asr 或 PUT /voice/tts
 UpdatingVoiceConfig --> VoiceConfigSaved: 写入YAML并reload ASR/TTS服务
 UpdatingVoiceConfig --> Error: 配置写入失败

 VoiceConfigLoaded --> TestingAsr: POST /voice/asr/test
 TestingAsr --> AsrTestSuccess: WebSocket端口连接成功
 TestingAsr --> AsrTestFailed: 连接失败
 AsrTestSuccess --> VoiceConfigLoaded
 AsrTestFailed --> VoiceConfigLoaded

 Error --> ProviderConfigPage: 前端提示错误后返回配置页

核心设计

llm-provider 模块的核心是把“模型配置读取、密钥保护、默认模型选择、运行时客户端缓存”放在同一套服务中管理。

DB 模式下，Provider 配置来自数据库。服务层读取 LlmProviderEntity 后，会先解密 API Key，再做脱敏，然后转换为 ProviderDTO 返回给前端。API Key 明文只在服务端运行时短暂出现，不会通过接口返回。

Legacy 模式下，Provider 配置来自 ConfigurationProperties。创建、更新和删除时会同步修改 YAML 配置文件和 .env 文件，并在修改完成后重载 Provider 注册表。

模块通过 rwLock 控制并发读写：查询类接口使用读锁，创建、更新、删除和默认值修改使用写锁，避免配置在读写过程中出现不一致。

Provider 列表查询

`GET /api/llm-provider/list` 获取全部 Provider 列表

Result<List<ProviderDTO>>

调用链：

providerController.listProviders();
providerService.listProviders();
globalSettingRepository.findById(1L);
providerRepository.findAll();
encryptionService.decrypt(nonce, ciphertext);

处理流程：

Controller 调用 listProviders()。
Service 获取 rwLock.readLock()。
DB 模式下先查询全局配置，用于判断默认 Chat Provider 和默认 Embedding Provider。
查询全部 LlmProviderEntity。
遍历每个 Provider：
- 解密 API Key。
- 调用 maskApiKey(...) 脱敏。
- 调用 resolveEmbeddingDimensions(...) 解析向量维度，未配置时使用全局默认值。
- 映射为 ProviderDTO。
Legacy 模式下从 properties.getProviders() 读取内存配置。
返回 Provider 列表。

关键点：

DB 模式读取失败时会抛出 BusinessException(PROVIDER_CONFIG_READ_FAILED)。
API Key 永远不会以明文返回给前端。
当前存在一个问题：如果已启用 DB 存储 LLM 配置，更新配置文件和 API Key 后，即使重启项目也不会自动同步到 DB，除非关闭 DB 模式或清理数据库配置。

`GET /api/llm-provider/{id}` 获取单个 Provider 详情

Result<ProviderDTO>

处理流程：

Controller 接收 Provider id。
Service 获取读锁。
DB 模式下查询全局配置和目标 Provider。
Provider 不存在时抛出 BusinessException(PROVIDER_NOT_FOUND)。
解密 API Key 后脱敏。
解析 Embedding 维度并构建 ProviderDTO。
Legacy 模式下从内存配置中按 id 获取 Provider。

Provider 创建与更新

`POST /api/llm-provider` 创建新 Provider

Result<Void>

调用链：

providerService.createProvider(request);
providerRepository.existsById(request.id());
validateEmbeddingConfig(...);
encryptionService.encrypt(apiKey);
providerRepository.save(entity);
registry.reload();

处理流程：

Controller 接收 CreateProviderRequest。
通过 @Valid 校验 id、baseUrl、apiKey、model 均不能为空。
Service 开启事务并获取写锁。
DB 模式下先检查 Provider ID 是否已存在。
对 baseUrl、model、apiKey 做二次非空校验。
调用 validateEmbeddingConfig(...) 校验 Embedding 配置。
使用 encryptionService.encrypt(apiKey) 加密 API Key。
保存 LlmProviderEntity。
调用 registry.reload() 清空运行时缓存。

Legacy 模式处理：

检查 properties.getProviders() 中是否已有相同 ID。
构建 ProviderConfig 并写入内存 Map。
调用 writeProviderToYaml(...) 写回 YAML。
调用 writeEnvValue(...) 写入 .env。
调用 registry.reload() 重载缓存。

Embedding 校验逻辑：

supportsEmbedding = true
embeddingModel == null // 抛出错误
looksLikeChatModel(...) // 抛出错误并给出推荐
embeddingDimensions <= 0 // 抛出错误

`PUT /api/llm-provider/{id}` 更新 Provider

Result<Void>

调用链：

providerService.updateProvider(id, request);
providerRepository.findById(id);
validateEmbeddingConfig(...);
encryptionService.encrypt(newApiKey);
providerRepository.save(entity);
registry.reload();

处理流程：

Controller 接收 Provider id 和 UpdateProviderRequest。
Service 开启事务并获取写锁。
DB 模式下根据 id 查询 Provider。
Provider 不存在时抛出 BusinessException(PROVIDER_NOT_FOUND)。
按字段更新配置：
- baseUrl：null 表示不修改，空字符串非法。
- model：null 表示不修改，空字符串非法。
- apiKey：null 表示不修改，空字符串非法，更新时重新加密。
- embeddingModel：允许传 null 清除。
- embeddingDimensions：按请求值更新。
- supportsEmbedding：按请求值更新。
- temperature：按请求值更新。
调用 validateEmbeddingConfig(...) 做完整校验。
保存实体并重载缓存。

注意：

UpdateProviderRequest 没有 @Valid，所有字段都是可选字段。
null 表示不更新。
空字符串视为非法输入。

Provider 删除与重载

`DELETE /api/llm-provider/{id}` 删除 Provider

Result<Void>

处理流程：

Service 开启事务并获取写锁。
DB 模式下读取全局设置。
判断当前 Provider 是否为默认 Chat Provider 或默认 Embedding Provider。
如果是默认 Provider，抛出 BusinessException(PROVIDER_DEFAULT_CANNOT_DELETE)。
查询目标 Provider，确认存在后删除。
调用 registry.reload() 清空运行时缓存。

Legacy 模式处理：

检查是否为默认 Provider。
从内存 Map 中删除配置。
调用 removeProviderFromYaml(...) 删除 YAML 节点。
调用 removeFromEnv(...) 删除 .env 中的 API Key。
调用 registry.reload() 重载缓存。

保护机制：

默认 Chat Provider 和默认 Embedding Provider 不允许直接删除。
必须先切换默认值，再删除原 Provider。

`POST /api/llm-provider/reload` 手动重载 Provider 缓存

Result<Void>

处理逻辑：

registry.reload();
clientCache.clear();
embeddingModelCache.clear();

说明：

该接口不加锁。
不开启事务。
不访问 DB。
只清空内存中的 ChatClient 和 EmbeddingModel 缓存。
下次调用 getChatClient() 或获取 Embedding 模型时按最新配置重新构建。

Provider 连通性测试

`POST /api/llm-provider/{id}/test` 测试 Provider 连接

Result<ProviderTestResult>

处理流程：

Service 获取读锁。
根据模式读取运行时配置：
- DB 模式下调用 getProviderRuntimeConfigOrThrow(id)。
- Legacy 模式下调用 toRuntimeConfig(...)。
构建 RestClient：
- connectTimeout = 5s
- readTimeout = 10s
- Header 中设置 Authorization: Bearer {apiKey}
构建测试请求体：

{
 "model": "xxx",
 "messages": [
 {
 "role": "user",
 "content": "Reply with OK only."
 }
 ],
 "max_tokens": 1
}

构建候选测试 URL：
- baseUrl + "/chat/completions"
- 如果 baseUrl 不含版本号，再尝试 baseUrl + "/v1/chat/completions"
依次向候选 URL 发送 POST 请求。
任一 URL 成功时返回连接成功。
全部失败时返回最后一次失败原因。

说明：

这是 Provider 管理中唯一会直接调用外部 LLM API 的接口。
测试请求会发送真实 HTTP 请求。
HTTP 错误会记录状态码和响应体，普通异常会记录异常类型和错误信息。

默认 Provider 管理

`GET /api/llm-provider/default-provider` 获取默认 Provider

Result<DefaultProviderDTO>

处理流程：

Service 获取读锁。
DB 模式下查询 globalSettingRepository.findById(1L)。
返回默认 Chat Provider ID 和默认 Embedding Provider ID。
Legacy 模式下从 properties.defaultProvider 和 properties.defaultEmbeddingProvider 构建返回值。

返回结构：

{
 "defaultProvider": "dashscope",
 "defaultEmbeddingProvider": "dashscope"
}

`PUT /api/llm-provider/default-provider` 设置默认 Chat Provider

Result<Void>

处理流程：

Service 开启事务并获取写锁。
读取 request.defaultProvider()。
默认 Provider 为空时抛出 BAD_REQUEST。
查询目标 Provider，确认存在。
DB 模式下更新 GlobalSettingEntity.defaultChatProviderId。
保存全局设置。
调用 registry.reload()。

Legacy 模式处理：

校验 Provider 存在。
修改 properties.setDefaultProvider(providerId)。
调用 writeDefaultProviderToYaml(providerId) 写回配置。
删除旧的 module-defaults 配置。
调用 registry.reload()。

`PUT /api/llm-provider/default-embedding-provider` 设置默认 Embedding Provider

Result<Void>

处理流程：

Service 开启事务并获取写锁。
读取 request.defaultEmbeddingProvider()。
默认 Embedding Provider 为空时抛出 BAD_REQUEST。
查询目标 Provider，确认存在。
校验该 Provider 支持 Embedding：
- supportsEmbedding 必须为 true。
- embeddingModel 必须存在。
- validateEmbeddingConfig(...) 必须通过。
DB 模式下更新 GlobalSettingEntity.defaultEmbeddingProviderId。
保存全局设置。
调用 registry.reload()。

与默认 Chat Provider 的差异：

设置默认 Embedding Provider 时多了 Embedding 能力校验。
不支持 Embedding 的 Provider 不能被设置为默认向量服务。

ASR 配置管理

`GET /api/llm-provider/voice/asr` 获取 ASR 配置

Result<AsrConfigDTO>

处理流程：

Service 获取读锁。
从 VoiceInterviewProperties 读取 voiceProperties.getQwen().getAsr()。
构建 AsrConfigDTO：
- url
- model
- language
- format
- sampleRate
- maskedApiKey
- enableTurnDetection
- turnDetectionType
- turnDetectionThreshold
- turnDetectionSilenceDurationMs
- VAD 相关参数
返回脱敏后的 ASR 配置。

说明：

ASR 配置来源于 VoiceInterviewProperties。
配置前缀是 app.voice-interview。
该配置不走 DB。

`PUT /api/llm-provider/voice/asr` 更新 ASR 配置

Result<Void>

处理流程：

Service 获取写锁。
读取运行时 ASR 和 TTS 配置引用。
按字段更新 ASR 配置：
- url
- model
- language
- format
- sampleRate
- enableTurnDetection
- turnDetectionType
- turnDetectionThreshold
- turnDetectionSilenceDurationMs
如果更新了 API Key，则同步更新 ASR 和 TTS：

asr.setApiKey(apiKey);
tts.setApiKey(apiKey);
updateEnvValue("AI_BAILIAN_API_KEY", apiKey);

调用 writeAsrConfigToYaml(asr) 写回 YAML。
调用 asrService.reload(voiceProperties) 重载 ASR 服务。
如果 API Key 更新，则同步调用 ttsService.reload(voiceProperties)。

注意：

该方法没有 @Transactional。
ASR 和 TTS 共享百炼 API Key。
修改 ASR 的 API Key 会同步影响 TTS。

TTS 配置管理

`GET /api/llm-provider/voice/tts` 获取 TTS 配置

Result<TtsConfigDTO>

处理流程：

Service 获取读锁。
从 VoiceInterviewProperties 读取 voiceProperties.getQwen().getTts()。
构建 TtsConfigDTO：
- model
- maskedApiKey
- voice
- format
- sampleRate
- mode
- languageType
- speechRate
- volume
返回脱敏后的 TTS 配置。

`PUT /api/llm-provider/voice/tts` 更新 TTS 配置

Result<Void>

处理流程：

Service 获取写锁。
读取运行时 ASR 和 TTS 配置引用。
按字段更新 TTS 配置：
- model
- voice
- format
- sampleRate
- mode
- languageType
- speechRate
- volume
如果更新了 API Key，则同步更新 TTS 和 ASR：

tts.setApiKey(apiKey);
asr.setApiKey(apiKey);
updateEnvValue("AI_BAILIAN_API_KEY", apiKey);

调用 writeTtsConfigToYaml(tts) 写回 YAML。
调用 ttsService.reload(voiceProperties) 重载 TTS 服务。
如果 API Key 更新，则同步调用 asrService.reload(voiceProperties)。

说明：

TTS 更新逻辑与 ASR 对称。
ASR/TTS 的 API Key 始终联动更新。

ASR 连通性测试

`POST /api/llm-provider/voice/asr/test` 测试 ASR 连接

Result<ProviderTestResult>

处理流程：

Service 获取读锁。
从 voiceProperties.getQwen().getAsr() 读取 ASR 配置。
解析 WebSocket URL：
- wss 默认端口为 443。
- ws 默认端口为 80。
使用 TCP Socket 发起连接测试：

socket.connect(address, 5000);
socket.close();

连接成功时返回：

ProviderTestResult(success=true, "ASR WebSocket 连接成功: host")

连接失败时返回失败原因。

与 Provider 连通性测试的差异：

ASR 测试只做 TCP Socket 连接。
不发送 WebSocket 握手。
不调用真实 ASR 识别接口。
Provider 测试会发送真实 HTTP 请求到 LLM 服务。

缓存与运行时行为

Provider 配置变更后都会调用 registry.reload()。这个方法会清空内部缓存：

clientCache.clear();
embeddingModelCache.clear();

因此，配置变更不会立即创建新的客户端，而是在下一次业务代码调用 Provider 时按需重建。这种方式避免了更新接口直接承担模型客户端初始化成本，也能保证旧配置不会长期停留在缓存中。

需要注意的是，reload 只负责清空缓存，不负责同步配置源。如果 DB 模式已经启用，系统会优先读取数据库配置，而不是重新从 YAML 或 .env 导入配置。

当前问题与优化方向

当前模块已经支持 DB 模式和 Legacy 模式，但配置同步边界还需要进一步明确：

DB 模式启用后，YAML 和 .env 的修改不会自动回写数据库。
重启项目只能重新加载运行时配置，不能解决 DB 配置与文件配置不一致的问题。
手动 reload 只清空运行时缓存，不会重新导入配置源。
ASR/TTS 配置仍来自 VoiceInterviewProperties，与 Provider DB 配置不是同一套存储。
ASR/TTS 更新方法没有事务，写 YAML、写 .env、服务重载之间存在部分成功的可能。

后续可按以下方向优化：

增加 DB 模式下的配置导入接口，用于从 YAML 和 .env 同步 Provider 到数据库。
在启动阶段增加一次性迁移策略，明确 DB 优先还是配置文件优先。
给 Provider 配置增加版本号或更新时间，便于排查缓存是否已刷新。
将 ASR/TTS 配置纳入统一配置存储，减少双配置源带来的不一致。
对 YAML 写入、.env 写入和服务重载增加失败补偿或更明确的错误提示。

小结

llm-provider 模块承担了大模型能力的统一配置入口。它不仅管理 Chat Provider，还管理 Embedding Provider、默认模型、运行时缓存和语音 ASR/TTS 配置。模块的关键价值在于：把模型配置和业务调用解耦，让知识库、RAG 聊天、语音面试等上层能力都可以通过统一 Provider 注册表获取模型能力。后续重点是进一步梳理 DB 配置和文件配置的同步机制，让配置来源更清晰、运行时状态更可控。

Transformer 20 步可视化学习笔记

Fri, 05 Jun 2026 23:10:00 +0800

Transformer 20 步可视化学习笔记

本文参考 Transformer Explainer 的交互式讲解，按它的 20 个步骤整理一篇中文学习笔记。这个网站用 GPT-2 small 作为示例模型，把文本生成过程可视化成从输入 token 到输出概率的完整流水线。

先记住一句话：GPT 类 Transformer 的核心任务是下一个 token 预测。给定提示词：

Data visualization empowers users to

模型要回答的问题是：

下一个最可能出现的 token 是什么？

为了回答这个问题，Transformer 会经历：分词、嵌入、位置编码、多层 Transformer Block、自注意力、MLP、logits、概率分布、采样策略等步骤。

本文所有步骤截图均截取自 Transformer Explainer，该项目由 Georgia Tech Polo Club 团队开发。截图用于个人学习笔记，建议结合原网站交互查看。

What is Transformer：Transformer 是什么

Transformer 是现代大语言模型最常用的基础架构。GPT、Llama、Gemini 这类文本生成模型，核心都可以理解为 Transformer 架构的扩展版本。

它最重要的能力不是“背答案”，而是从大量文本中学会语言模式，然后在推理时根据上下文预测下一个 token。这个预测会反复进行：预测一个 token，把它接到原文本后面，再继续预测下一个。

图源：Transformer Explainer，https://poloclub.github.io/transformer-explainer/

How Transformers Work：文本生成的本质

Transformer 生成文本时并不是一次性写完整段话，而是逐步生成。每一步都在做同一个任务：根据已有上下文，预测下一个 token 的概率分布。

例如当前输入是：

Data visualization empowers users to

模型可能认为下一个 token 是 visualize 的概率最高，也可能给 create、see、make 等 token 分配较高概率。最终输出哪个 token，还会受到 temperature、top-k、top-p 等采样参数影响。

图源：Transformer Explainer

Transformer Architecture：整体架构

一个文本生成 Transformer 可以拆成三大部分：

Embedding：把人类文本变成模型能处理的向量。
Transformer Blocks：反复加工每个 token 的表示，核心包括 Self-Attention 和 MLP。
Output Probabilities：把最终向量变成词表中每个 token 的概率。

从宏观上看，信息流是：

文本输入 -> token -> embedding -> 多层 Transformer Block -> logits -> 概率 -> 采样下一个 token

图源：Transformer Explainer

Embedding：把文本变成向量

模型不能直接理解字符串。Embedding 的作用是把每个 token 转成一串数字，也就是向量。这个向量不是随便编码的，而是在训练过程中学出来的。

如果两个 token 经常出现在相似语境中，它们的 embedding 往往会在高维空间中更接近。可以把 embedding 理解成模型内部的“词义坐标”。

GPT-2 small 的隐藏维度是 768，所以每个 token 会被表示成一个 768 维向量。

图源：Transformer Explainer

Token Embedding：分词与 token 查表

Tokenization 会把输入文本切成 token。token 可以是完整单词，也可以是子词。例如示例里的 empowers 被切成了 em 和 powers。

每个 token 都有一个唯一 ID。GPT-2 的词表大小是 50,257，所以 token embedding 矩阵大致是：

$$ 50257 \times 768 $$

模型拿到 token ID 后，会去这个大矩阵里查出对应的 768 维向量。

图源：Transformer Explainer

Positional Encoding：注入位置信息

Self-Attention 本身不天然知道顺序。如果只给模型一组 token 向量，它并不知道哪个 token 在前、哪个在后。

所以需要位置编码。GPT-2 使用可学习的位置 embedding，把 token 的语义向量和位置向量相加：

$$ x_i = \text{TokenEmbedding}_i + \text{PositionEmbedding}_i $$

这样模型既知道“这个 token 是什么”，也知道“它在第几个位置”。

图源：Transformer Explainer

Repetitive Transformer Blocks：重复堆叠的 Transformer Block

Embedding 只是输入表示，还不是充分理解后的语义表示。真正的上下文建模发生在 Transformer Block 中。

GPT-2 small 有 12 个 Transformer Block。每个 block 大致包含：

Multi-Head Self-Attention：让 token 之间交换信息。
MLP：对每个 token 的表示做非线性加工。
Residual、LayerNorm、Dropout：让训练更稳定，泛化更好。

多层堆叠的意义是：底层更偏局部和词法信息，高层更容易形成复杂语义和任务相关表示。

图源：Transformer Explainer

Multi-Head Self Attention：多头自注意力

Self-Attention 的目标是让每个 token 根据上下文更新自己。比如 to 这个 token 在不同句子里含义不同，它需要“看”前面的 Data visualization empowers users，才能形成更准确的表示。

Multi-Head 的含义是：模型不是只用一种注意力视角，而是并行使用多个 head。GPT-2 small 有 12 个 attention heads。不同 head 可以学习不同关系，例如语法关系、短距离搭配、长距离语义依赖等。

图源：Transformer Explainer

Query, Key, Value：Q、K、V 是什么

Self-Attention 会把每个 token 的输入向量分别映射成三个向量：

Query (Q)：当前 token 想查什么信息。
Key (K)：每个 token 能被别人匹配到的特征。
Value (V)：真正要被聚合传递的信息内容。

它们来自线性变换：

$$ Q = XW_Q,\quad K = XW_K,\quad V = XW_V $$

一个通俗类比是搜索引擎：

Query 是搜索词。
Key 是网页标题或索引。
Value 是网页正文内容。

先用 Query 和 Key 算相关性，再根据相关性加权读取 Value。

图源：Transformer Explainer

Multi-head：把 Q/K/V 切成多个头

GPT-2 small 的 embedding 维度是 768，attention head 数是 12，所以每个 head 处理的维度通常是：

$$ 768 / 12 = 64 $$

多头机制的好处是并行学习多种关系。一个 head 可能关注相邻词，另一个 head 可能关注主谓关系，还有 head 可能关注更远处的语义提示。

多个 head 不是重复劳动，而是让模型拥有多个“观察角度”。

图源：Transformer Explainer

Masked Self Attention：带掩码的自注意力

GPT 这类模型是从左到右生成文本的。预测当前位置时，不能偷看未来 token，所以要使用 causal mask，也叫 masked self-attention。

核心计算公式是：

$$ \text{Attention}(Q,K,V)=\text{softmax}\left(\frac{QK^T}{\sqrt{d_k}} + M\right)V $$

其中：

$QK^T$：计算 token 两两之间的相似度。
$\sqrt{d_k}$：缩放因子，避免点积值过大导致 softmax 过尖。
$M$：mask 矩阵，把未来位置设为 $-\infty$。
softmax：把分数变成概率。
乘以 $V$：按注意力权重汇总信息。

图源：Transformer Explainer

Attention Output & Concatenation：注意力输出与拼接

每个 head 都会输出一份上下文增强后的 token 表示。因为 GPT-2 small 有 12 个 head，所以会得到 12 份结果。

接下来模型会把这些 head 的输出拼接起来，再经过一次线性投影，回到原来的隐藏维度 768：

head_1, head_2, ..., head_12 -> concat -> linear projection

这一步的意义是：先让多个 head 分别提取信息，再把多种视角融合成一个统一表示。

图源：Transformer Explainer

MLP：逐 token 的非线性加工

Attention 负责 token 之间的信息流动，MLP 负责对每个 token 自己的表示进行加工。

GPT-2 的 MLP 通常包含两层线性变换，中间接 GELU 激活：

$$ \text{MLP}(x)=W_2\cdot \text{GELU}(W_1x+b_1)+b_2 $$

第一层会把维度从 768 扩展到 3072，第二层再压回 768。扩展维度可以让模型在更高维空间中表达更复杂的特征。

注意：MLP 不像 Attention 那样跨 token 交流信息，它是对每个 token 独立处理。

图源：Transformer Explainer

Output Logit：输出 logits

经过所有 Transformer Blocks 后，模型会拿最后一个位置的输出向量去预测下一个 token。

这个向量会经过最终线性层，映射到词表大小：

$$ \text{logits}=h_{\text{last}}W_{\text{vocab}}+b $$

GPT-2 的词表大小是 50,257，所以 logits 是一个长度为 50,257 的向量。每个数对应一个候选 token 的原始分数。

logit 不是概率。它可以是任意实数，还需要经过 softmax 才能变成概率分布。

图源：Transformer Explainer

Probabilities：从 logits 到概率

Softmax 会把 logits 转换成概率：

$$ p_i=\frac{e^{z_i}}{\sum_j e^{z_j}} $$

转换后有两个特点：

每个 token 的概率都在 0 到 1 之间。
所有 token 的概率加起来等于 1。

图中可以看到，示例输入后，模型认为 visualize、create、see、make 等 token 是比较可能的下一个 token。

图源：Transformer Explainer

Temperature：温度控制生成随机性

Temperature 会在 softmax 前缩放 logits：

$$ p_i=\frac{\exp(z_i/T)}{\sum_j \exp(z_j/T)} $$

其中 $T$ 是 temperature：

$T < 1$：概率分布更尖锐，高分 token 更容易被选中，输出更稳定。
$T = 1$：不额外调整 logits。
$T > 1$：概率分布更平坦，低概率 token 也有更多机会被选中，输出更多样。

通俗地说，temperature 越低越保守，越高越发散。

图源：Transformer Explainer

Sampling Strategy：采样策略

得到概率分布后，模型还要决定如何选下一个 token。常见策略有：

Greedy Search：永远选概率最高的 token，稳定但容易死板。
Top-k：只保留概率最高的 k 个 token，再从中采样。
Top-p：保留累计概率达到 p 的最小 token 集合，也叫 nucleus sampling。

Top-k 更像固定候选池，Top-p 更像动态候选池。实际使用时，temperature 和 top-k/top-p 经常一起调。

图源：Transformer Explainer

Residual Connection：残差连接

残差连接会把某一层的输入直接加到输出上：

$$ y = x + F(x) $$

它的作用是保留原始信息，并让梯度更容易穿过深层网络。如果没有残差连接，模型层数很深时，训练会更困难，早期层的信息也更容易丢失。

在 Transformer 中，Attention 和 MLP 周围通常都有残差连接。

图源：Transformer Explainer

Layer Normalization：层归一化

Layer Normalization 会对一个 token 向量内部的数值做归一化，使均值和方差更稳定：

$$ \text{LayerNorm}(x)=\gamma\frac{x-\mu}{\sqrt{\sigma^2+\epsilon}}+\beta $$

它能减少训练不稳定，让每一层输入分布更可控。GPT-2 使用的是 pre-norm 风格：在进入 Attention 和 MLP 前先做 LayerNorm。

通俗理解：LayerNorm 像是在每次进入关键计算前，先把数值尺度整理到比较合适的范围。

图源：Transformer Explainer

Dropout：训练时的随机失活

Dropout 是训练阶段的正则化方法，会随机把一部分连接或激活置零，避免模型过度依赖某些局部特征。

它的直觉是：训练时不要让模型每次都走完全相同的路径，迫使它学到更稳健的表示。

需要注意：

Dropout 主要用于训练。
推理时 Dropout 会关闭。
很多新一代大模型因为训练数据极大，Dropout 使用得比早期模型更少。

图源：Transformer Explainer

一张流程图总结

可以把 GPT 类 Transformer 的推理流程压缩成下面这条链路：

flowchart LR
 A["输入文本"] --> B["Tokenization"]
 B --> C["Token Embedding"]
 C --> D["Positional Encoding"]
 D --> E["Transformer Block x N"]
 E --> F["Multi-Head Self-Attention"]
 F --> G["MLP"]
 G --> H["Final Linear"]
 H --> I["Logits"]
 I --> J["Softmax Probabilities"]
 J --> K["Temperature / Top-k / Top-p"]
 K --> L["采样下一个 token"]

和 RNN 的关键区别

结合之前的 RNN 学习，可以这样理解二者差异：

对比点	RNN	Transformer
信息传递方式	依赖隐藏状态逐步传递	Self-Attention 让 token 直接互相读取
并行能力	时间步依赖强，难并行	同层 token 可并行计算
长距离依赖	路径长，容易衰减	任意位置可直接建立联系
上下文表示	压缩进隐藏状态	显式保留整段 token 表示
大模型训练	扩展效率较差	更适合 GPU/TPU 大规模矩阵计算

这也是为什么现代 LLM 主流选择 Transformer：它不仅建模能力强，而且工程上更适合大规模预训练。

LLM on XEDCZQ的博客

Ai面试项目：llm-provider模块

Llm-provider 模块设计与实现

模块能力概览

流程图

核心设计

Provider 列表查询

GET /api/llm-provider/list 获取全部 Provider 列表

GET /api/llm-provider/{id} 获取单个 Provider 详情

Provider 创建与更新

POST /api/llm-provider 创建新 Provider

PUT /api/llm-provider/{id} 更新 Provider

Provider 删除与重载

DELETE /api/llm-provider/{id} 删除 Provider

POST /api/llm-provider/reload 手动重载 Provider 缓存

Provider 连通性测试

POST /api/llm-provider/{id}/test 测试 Provider 连接

默认 Provider 管理

GET /api/llm-provider/default-provider 获取默认 Provider

PUT /api/llm-provider/default-provider 设置默认 Chat Provider

PUT /api/llm-provider/default-embedding-provider 设置默认 Embedding Provider

ASR 配置管理

GET /api/llm-provider/voice/asr 获取 ASR 配置

PUT /api/llm-provider/voice/asr 更新 ASR 配置

TTS 配置管理

GET /api/llm-provider/voice/tts 获取 TTS 配置

PUT /api/llm-provider/voice/tts 更新 TTS 配置

ASR 连通性测试

POST /api/llm-provider/voice/asr/test 测试 ASR 连接

缓存与运行时行为

当前问题与优化方向

小结

Transformer 20 步可视化学习笔记

Transformer 20 步可视化学习笔记

What is Transformer：Transformer 是什么

How Transformers Work：文本生成的本质

Transformer Architecture：整体架构

Embedding：把文本变成向量

Token Embedding：分词与 token 查表

Positional Encoding：注入位置信息

Repetitive Transformer Blocks：重复堆叠的 Transformer Block

Multi-Head Self Attention：多头自注意力

Query, Key, Value：Q、K、V 是什么

Multi-head：把 Q/K/V 切成多个头

Masked Self Attention：带掩码的自注意力

Attention Output & Concatenation：注意力输出与拼接

MLP：逐 token 的非线性加工

Output Logit：输出 logits

Probabilities：从 logits 到概率

Temperature：温度控制生成随机性

Sampling Strategy：采样策略

Residual Connection：残差连接

Layer Normalization：层归一化

Dropout：训练时的随机失活

一张流程图总结

和 RNN 的关键区别

学习来源

`GET /api/llm-provider/list` 获取全部 Provider 列表

`GET /api/llm-provider/{id}` 获取单个 Provider 详情

`POST /api/llm-provider` 创建新 Provider

`PUT /api/llm-provider/{id}` 更新 Provider

`DELETE /api/llm-provider/{id}` 删除 Provider

`POST /api/llm-provider/reload` 手动重载 Provider 缓存

`POST /api/llm-provider/{id}/test` 测试 Provider 连接

`GET /api/llm-provider/default-provider` 获取默认 Provider

`PUT /api/llm-provider/default-provider` 设置默认 Chat Provider

`PUT /api/llm-provider/default-embedding-provider` 设置默认 Embedding Provider

`GET /api/llm-provider/voice/asr` 获取 ASR 配置

`PUT /api/llm-provider/voice/asr` 更新 ASR 配置

`GET /api/llm-provider/voice/tts` 获取 TTS 配置

`PUT /api/llm-provider/voice/tts` 更新 TTS 配置

`POST /api/llm-provider/voice/asr/test` 测试 ASR 连接