多语言支持
本章系统说明语言标记（language flag）在 RAG 系统中的生命周期：客户端语言检测 → 向量检索过滤 → Prompt 构建 → 模型生成 → UI 渲染，以及在检索阶段的回退与后续优化方向。下文将通过序列图和关键环节解析，逐步梳理多语言支持的实现细节。
原始序列图（Sequence Diagram）
在多语言 RAG 系统中，语言标记的全链路传递至关重要。下方序列图直观展示了从客户端检测到检索、回退、Prompt 构建、模型生成再到 UI 渲染的完整流程，帮助理解各环节如何协同保证语言一致性与体验稳定性。
多语言流程的每个环节都依赖于语言标记的准确传递，下面将逐步解析关键实现细节。
关键环节解析
首先，客户端需要准确检测用户所用语言，为后续流程打下基础。
客户端语言检测
最小逻辑：路径以 /en/ 开头即英文，否则中文。可扩展优先级：URL → <html lang> → meta → navigator.language → 默认 zh。
语言检测完成后，内容在 Ingestion 阶段会写入元数据，便于后续检索。
Ingestion 阶段元数据写入
fast-ingest.ts 中基于文件路径推断语言写入 language 字段，随后向量条目（Vector Item）包含：{ id, vector, text, title, source, url, language }，便于检索端直接用 metadata 过滤。
检索阶段则采用两级策略，确保优先返回目标语言内容。
检索阶段两级策略
检索环节采用如下两步策略：
- 语言过滤查询（带
filter.metadata.language，设置 500ms 超时）。 - 失败 / 超时 / 空结果 → 无过滤查询 + URL 二次过滤（英文优先保留
/en/，否则回退中文；中文直接排除/en/）。
检索结果用于 Prompt 构建，语言分支确保上下文和指令一致。
Prompt 构建语言分支
buildPrompt() 根据语言切换：
- System 角色设定文本
- 对话历史标签（User / Assistant vs 用户 / 助手）
- 指令用语
模型生成后，前端渲染阶段根据语言标记进行本地化处理。
回答与前端渲染
后端仅返回 { answer, sources }，前端依据语言选择本地化 UI 字段（如来源标题、错误提示、按钮文案）。
为便于理解，下面提供一个伪代码示例，展示检索阶段的语言过滤与回退逻辑。
检索回退伪代码示例
以下代码演示了如何优先进行语言过滤检索，若无结果则回退并做二次过滤：
async function getRelevantDocuments(env, qvec, k, lang) {
try {
const filtered = await env.VECTORIZE.query(qvec, { filter: { metadata: { language: lang } }, topK: k });
if (!filtered.matches.length) throw new Error('Empty filtered');
return { matches: filtered.matches, usedFallback: false };
} catch (e) {
const all = await env.VECTORIZE.query(qvec, { topK: k });
const post = all.matches.filter(m => lang === 'en' ? m.metadata?.url?.includes('/en/') : !m.metadata?.url?.includes('/en/'));
return { matches: post, usedFallback: true };
}
}
此外，系统支持手动向量更新，便于内容维护。
手动向量更新说明
通过 manual-ingest.ts 指定文件重新嵌入并 upsert：
npm run manual-ingest content/zh/blog/example/index.md
多语言支持过程中，已解决若干实际问题，具体如下。
已解决问题简述
下表总结了多语言流程优化前后的变化：
| 问题 | 旧状况 | 现状 | 效果 |
|---|---|---|---|
| 语言默认不一致 | 客户端 / 服务端判定不同 | 统一默认 zh | 减少错配 |
| 回退后语料混杂 | 中英文混合 | URL 二次过滤 | 输出稳定 |
| 历史标签混乱 | 混用英文标签 | 分支标签 | 上下文清晰 |
为进一步提升体验，建议持续优化如下方面。
改进建议概览
多语言流程仍有优化空间，建议：
- localStorage 记忆语言偏好。
- 增加显式语言切换 UI → 同步发送
language字段。 - 记录 fallback / 超时指标用于可观测性。
- 500ms 超时设为可配置环境变量。
小结
语言标记贯穿 RAG 全链路：检测 → 元数据 → 检索过滤 / 回退 → Prompt 选择 → 渲染。通过“优先过滤 + 回退再过滤”策略确保多语言一致性，并在缺失目标语言语料时仍能平滑降级。