企业官网建设流程全解析

Hindsight 多语言记忆系统：从语言感知的事实提取到 BM25 索引选型

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

本文基于 Hindsight 官方文档《Multilingual Support》展开，深入讲解该项目如何实现"输入什么语言、记忆与响应就保持什么语言"的多语言能力：包括 retain/recall/reflect 全流程中的语言保持机制、多语言嵌入与重排模型配置、五种 BM25 全文检索后端的 CJK 适配差异，以及HINDSIGHT_API_LLM_OUTPUT_LANGUAGE强制输出语言参数的底层实现。读完后你可以为一套中文/日文为主的 Agent 记忆库完成完整的模型与索引选型，并理解每条配置在源码中的实际作用点。

核心机制：用 LLM Prompt 指令实现语言检测

Hindsight 会自动检测输入内容的语言，并让事实（facts）、实体（entities）和 reflect 响应保持原始语言，而不会翻译成英文。官方给出的处理链路如下：

当你 retain 内容或发起 reflect 查询时，Hindsight 会依次完成四步：

1. 自动检测输入语言——从内容本身推断；
2. 以原始语言提取事实——保留语气与语义细节；
3. 以原生文字存储实体——"张伟" 保持为 "张伟"，而不是 "Zhang Wei"；
4. 以相同语言响应——中文查询得到中文回答。

值得强调的是，文档"Technical Details"部分明确指出：多语言支持完全通过 LLM Prompt 指令实现，而不是依赖外部语言检测库。从源码可以印证这一点：retain 的事实提取 Prompt 中直接内置了一条强制性的语言规则，见 fact_extraction.py：

LANGUAGE: MANDATORY — Detect the language of the input text and produce ALL output in that EXACT same language. You are STRICTLY FORBIDDEN from translating or switching to any other language. Every single word of your output must be in the same language as the input. ...

这条规则被注入 retain、consolidation、reflect 各环节的 Prompt 模板（模板中含{language_section}占位符）。这种方案的好处是文档所列的四点：无额外依赖、适用于任何支持多语言的 LLM、天然处理混合语言边缘情况、比基于规则的翻译更好地保留语义。

Retain 非英文内容

retain 任意语言的内容时，Hindsight 都会以相同语言提取并存储事实。

示例：中文内容

from hindsight import Hindsight hindsight = Hindsight() # Retain 中文内容 hindsight.retain( bank_id="user-123", content=""" 张伟是一位资深软件工程师，在腾讯工作了五年。 他专门研究分布式系统，并领导了公司微服务架构的开发。 """, context="团队概述" ) # 用中文查询——得到中文结果 results = hindsight.recall( bank_id="user-123", query="告诉我关于张伟的信息" ) # 事实以中文返回： # - 张伟是一位资深软件工程师，在腾讯工作了五年 # - 张伟专门研究分布式系统，并领导了公司微服务架构的开发

示例：日文内容

hindsight.retain( bank_id="user-123", content=""" 田中さんはソフトウェアエンジニアで、東京のスタートアップで働いています。 彼女はPythonとTypeScriptが得意で、毎日コードレビューをしています。 """, context="チームプロフィール" ) # 用日文查询 results = hindsight.recall( bank_id="user-123", query="田中さんについて教えてください" )

Reflect 对非英文查询的语言响应

reflect操作同样尊重输入语言，会以与查询相同的语言生成回答。

示例：中文反思

# 存储团队成员的事实（中文） hindsight.retain( bank_id="team-eval", content="张伟是一位优秀的软件工程师，完成了五个重大项目。他总是按时交付，代码整洁有良好的文档。", context="绩效评估" ) hindsight.retain( bank_id="team-eval", content="李明最近加入团队。他错过了第一个截止日期，代码有很多bug。", context="绩效评估" ) # 用中文 reflect result = hindsight.reflect( bank_id="team-eval", query="谁是更可靠的工程师？" ) # 响应为中文： # "我认为张伟更可靠。张伟完成了五个重大项目，按时交付，代码质量高..."

reflect 环节的语言控制同样来自 Prompt：reflect/prompts.py 与 reflect/agent.py 都会把语言指令（或强制语言指令）织入系统 Prompt 与工具 schema，保证最终的自然语言回答与查询同语言。

混合语言内容

Hindsight 也能优雅地处理混合语言内容，在合适的位置同时保留两种语言。

示例：含英文公司名的中文文本

hindsight.retain( bank_id="user-123", content=""" 王芳在Google北京办公室工作，她是一名高级产品经理。 之前她在Microsoft和Amazon工作过。 她负责管理YouTube在中国市场的推广策略。 """, context="员工资料" ) # 事实同时保留两种语言： # - 王芳在Google北京办公室工作，担任高级产品经理 # - 王芳曾在Microsoft和Amazon工作过 # - 王芳负责管理YouTube在中国市场的推广策略

这与源码中"专名永不翻译"的规则一致：prompt_utils.py 的语言指令明确要求实体名（entity names）保持原样，因此 Google、Microsoft、YouTube 等专有名词不会被转写。

支持的语言范围

Hindsight 的多语言能力完全取决于你所用 LLM 的语言能力。Hindsight 只是指示 LLM 检测输入语言并以该语言响应——如果 LLM 支持某种语言，Hindsight 就能处理它。

大多数现代 LLM（GPT-4、Claude、Gemini、Llama 3 等）支持数十种语言，包括：

• 东亚：中文（简体/繁体）、日文、韩文
• 欧洲：西班牙语、法语、德语、意大利语、葡萄牙语、荷兰语、波兰语、俄语
• 中东：阿拉伯语、希伯来语、土耳其语
• 南亚：印地语、孟加拉语、泰米尔语
• 东南亚：泰语、越南语、印尼语

验证目标语言支持的正确做法是直接用该语言内容测试你的 LLM：如果模型能理解并生成该语言文本，Hindsight 就能正确保持它。

多语言配置：四个组件的完整选型

要获得最优的多语言效果，需要配置管道的四个组件。下面逐个展开，并结合源码说明每个配置项的真实作用点。

1. LLM（必需）

你的 LLM 必须支持目标语言。大多数现代 LLM 都支持，但请用你实际使用的具体模型验证。

2. 嵌入模型（推荐）

默认嵌入模型BAAI/bge-small-en-v1.5是纯英文的——这一点在 config.py 中可以看到常量定义DEFAULT_EMBEDDINGS_LOCAL_MODEL = "BAAI/bge-small-en-v1.5"。对多语言内容，应改用多语言嵌入模型：

# 在 .env 文件中 HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-m3

推荐的多语言嵌入模型：

3. 重排模型（推荐）

默认重排器cross-encoder/ms-marco-MiniLM-L-6-v2同样是纯英文的（见 config.py 的DEFAULT_RERANKER_LOCAL_MODEL）。多语言内容请换用多语言重排器：

# 在 .env 文件中 HINDSIGHT_API_RERANKER_LOCAL_MODEL=BAAI/bge-reranker-v2-m3

推荐的多语言重排器模型：

4. BM25 / 全文检索后端

语义（嵌入）检索臂负责"按语义"的跨语言匹配；Hindsight 会并行运行一条 BM25 关键词检索臂。而BM25 本质上是语言内的——它是针对分词器词素的字符/token 精确匹配。默认的native后端使用 PostgreSQL 的英文词典，对非英文内容效果很差（对没有空格分词边界的中文/日文/韩文，更是完全无法有效分词）。

这里有两个相互关联的开关：

• HINDSIGHT_API_TEXT_SEARCH_EXTENSION——选择后端（native、vchord、pg_textsearch、pgroonga或pg_search）。
• HINDSIGHT_API_TEXT_SEARCH_EXTENSION_NATIVE_LANGUAGE——选择native后端使用的 PostgreSQL 词典（默认：english）。

按 bank 中存储的语言选择后端：

单语言 bank 的选型（例如全是西班牙语文本）：

HINDSIGHT_API_TEXT_SEARCH_EXTENSION=native HINDSIGHT_API_TEXT_SEARCH_EXTENSION_NATIVE_LANGUAGE=spanish

CJK 或多语言 bank 的选型：

HINDSIGHT_API_TEXT_SEARCH_EXTENSION=pgroonga

注意native与pgroonga的开关互不适用——pgroonga的分词器在索引创建时确定，会忽略HINDSIGHT_API_TEXT_SEARCH_EXTENSION_NATIVE_LANGUAGE。

从源码看，native后端的语言配置最终落地在 SQL 的to_tsvector调用上，ops_postgresql.py 会生成形如to_tsvector('{config.text_search_extension_native_language}'::regconfig, ...)的表达式，即 PostgreSQL 全文索引的词典由该参数直接决定。而 pgroonga 臂则调用pgroonga_tokenize(..., 'TokenBigram', 'NormalizerNFKC150')，这一点可在 test_multilingual_bm25.py 的断言中得到验证。配置项本身在 config.py 中定义，并且text_search_extension_native_language会经过 PostgreSQL 标识符合法性校验（正则[a-zA-Z_][a-zA-Z0-9_]*），防止拼入任意 SQL。

强制指定 LLM 输出语言

独立于 BM25 后端之外，HINDSIGHT_API_LLM_OUTPUT_LANGUAGE会把所有LLM 生成产物统一固定到单一语言，与源内容语言无关。它统一作用于：

• Retain——从源文档提取的事实文本、上下文、实体名；
• Consolidation——由这些事实合成的观察（observations）/ 心智模型；
• Reflect——reflect API 返回的最终自然语言响应。

# 所有 LLM 调用（retain、consolidation、reflect）无论源语言都输出西班牙语。 HINDSIGHT_API_LLM_OUTPUT_LANGUAGE=Spanish

这一机制的实现在 prompt_utils.py：output_language_directive()为 retain 的事实提取、consolidation 与 reflect 追加统一指令——

IMPORTANT: Respond exclusively in {language}. Translate any source content into {language}. All output text — including fact text, observations, entity names, and the final response — must be in {language}.

一个值得注意的实现细节：default_language_section()与output_language_directive()是互斥的——一旦设置了显式输出语言，"保持源语言"的默认规则会被整体移除，而不是与新指令并存（源码注释说明两条指令同时出现时，模型会因"保持源语言"规则语气更强而静默忽略配置，见 issue #3776 的记录）。相关行为可由 test_retain_reflect_output_language.py 与 test_consolidation_output_language.py 复验。

常见配置模式：

• 对齐的单语言 bank：HINDSIGHT_API_TEXT_SEARCH_EXTENSION_NATIVE_LANGUAGE=spanish+HINDSIGHT_API_LLM_OUTPUT_LANGUAGE=Spanish——即使源语言混杂，也以西班牙语存储、索引、响应；
• 带多语言索引的混合语言 bank：HINDSIGHT_API_TEXT_SEARCH_EXTENSION=pgroonga+ 不设置HINDSIGHT_API_LLM_OUTPUT_LANGUAGE——事实保持源语言；pgroonga 用单个索引处理所有语言；reflect 按查询语言响应；
• 跨语言归一化：HINDSIGHT_API_LLM_OUTPUT_LANGUAGE=English——无论源语言，所有事实、观察、reflect 响应统一为英文。适用于消费端（仅英文的 LLM、仪表盘或下游管道）需要统一输出格式的场景。

不设置HINDSIGHT_API_LLM_OUTPUT_LANGUAGE时，管道会保持源语言/查询语言（默认行为）。

未设置输出语言时的默认行为

不设置HINDSIGHT_API_LLM_OUTPUT_LANGUAGE时，retain 与 consolidation 都会被指示保持源材料语言输出。对 observations（观察）而言：

• 语言按单条 observation 决定，依据其构建所基于的事实——而不是整个批次。一个混合了中英文事实的批次，会为中文事实产出中文观察、为英文事实产出英文观察。若一条 observation 合并了多种语言的事实，则以这些事实中的多数语言为准。
• 更新跟随新事实的语言。当既有 observation 的语言与更新它的新事实不同时，整条 observation 会按新事实的语言重写。一个 observation 曾"漂移到错误语言"的 bank，会随着新事实到达而逐步收敛回来。
• 专名与技术术语永不翻译——专有名词、产品名、地名、标识符、代码、单位，无论周围语言是什么，都按源事实的原文保留。

需要明确边界：这是Prompt 级别的引导，不是硬保证——一个不遵守指令的模型仍可能输出错误语言。若某个 bank 必须无论源内容如何都保持单一语言，请显式设置HINDSIGHT_API_LLM_OUTPUT_LANGUAGE。

最佳实践

1. 非英文内容使用多语言模型

如果你的主要工作语言不是英文，请配置多语言嵌入与重排模型。纯英文模型仍能正确存储你的内容，但语义检索质量会下降。

2. 每次 retain 调用保持单一语言

混合内容虽然可以工作，但让每次retain调用集中在单一语言上，结果更一致。

3. 用与内容相同的语言查询

最佳效果是用与存储内容相同的语言查询。跨语言查询（例如用英文查询中文内容）可能有效，但效果取决于你的嵌入模型，结果会有波动。

小结

Hindsight 的多语言体系是一条完整的链路：语言检测与保持由 Prompt 指令完成（无需额外依赖库），嵌入/重排模型负责语义臂的跨语言能力，BM25 后端（pgroonga/pg_search等）负责语言内的关键词召回，而HINDSIGHT_API_LLM_OUTPUT_LANGUAGE则提供一条"一刀切"的归一化开关。部署 CJK 为主的记忆库时，官方文档与 docker/docker-compose/pgroonga/docker-compose.yaml、docker/docker-compose/pg_search/docker-compose.yaml 提供了可直接参考的容器化参考配置；完整文档见 hindsight-docs/versioned_docs/version-0.9/developer/multilingual.md。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight