Koog(9) —— 知识增强:Embeddings、RAG 与长期记忆

前言

上一篇讲工程化时留下一条预告:下一篇进入知识增强。这篇兑现——Embeddings、RAG 与长期记忆,也就是"让 agent 记住并找回知识"的整套设施。

先交代版本:本文继续采用 1.3.0 正式模块与 1.3.0-beta 预览模块混用的方式,各模块归属已对照发布版源码核验:

模块 版本 内容
embeddings-base / embeddings-llm 1.3.0 正式版 向量嵌入抽象与 Ollama 实现
rag-base 1.3.0 正式版 检索/存储抽象、搜索请求类型
rag-vector 1.3.0-beta 文档嵌入存储(EmbeddingStorage 等)
agents-features-longterm-memory 1.3.0-beta LongTermMemory feature

beta 部分经 koog-agents-additions:1.3.0-beta 传递,API 可能变化,涉及处会标注。本文采用的组合是:聊天请求真实 DeepSeek,检索走本地存储。这只是其中一种接法;DeepSeek 聊天同样可以搭配其他服务的嵌入模型、远端检索服务或自建向量库。DeepSeek 客户端的嵌入限制见 1.3。

关键代码直接列在对应章节:第二章的检索程序不调用模型;第四、五章的完整程序使用真实 DeepSeek,API Key 均以 "xxxxxxx" 占位。嵌入服务和 rag-vector 流程仅编译核验,未执行真实嵌入请求;模型输出保留既有真实运行的节选,不把本次编译检查当成新一轮在线实测。

一、Embeddings:把文本变成向量

1.1 模块结构

embeddings 拆成两个模块:embeddings-base 定义核心接口与数据结构;embeddings-llm 提供 LLMEmbedder——调用服务商的嵌入端点,并将响应包装为 Koog 的向量对象。入口非常薄:

import ai.koog.embeddings.local.LLMEmbedder
import ai.koog.prompt.executor.clients.bedrock.BedrockClientSettings
import ai.koog.prompt.executor.clients.bedrock.BedrockLLMClient
import ai.koog.prompt.executor.clients.bedrock.BedrockModels
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.clients.openai.OpenAILLMClient
import ai.koog.prompt.executor.ollama.client.OllamaClient
import ai.koog.prompt.executor.ollama.client.OllamaModels
import aws.sdk.kotlin.runtime.auth.credentials.StaticCredentialsProvider

// 片段:构造 LLMEmbedder 不发起任何网络请求,可离线编译验证。

// Ollama 本地(需本机安装 Ollama 并 ollama pull 模型)
val ollamaEmbedder = LLMEmbedder(
    client = OllamaClient(),
    model = OllamaModels.Embeddings.NOMIC_EMBED_TEXT
)

// OpenAI 云端
fun openAIEmbedder(apiKey: String) = LLMEmbedder(
    client = OpenAILLMClient(apiKey),
    model = OpenAIModels.Embeddings.TextEmbeddingAda002
)

// AWS Bedrock 云端(BedrockModels 是 JVM-only)。
// 注意 StaticCredentialsProvider 的真实包是 aws.sdk.kotlin.runtime.auth.credentials,
// 官方文档示例里的 import 编译不过。
fun bedrockEmbedder(accessKeyId: String, secretAccessKey: String) = LLMEmbedder(
    client = BedrockLLMClient(
        identityProvider = StaticCredentialsProvider {
            this.accessKeyId = accessKeyId
            this.secretAccessKey = secretAccessKey
        },
        settings = BedrockClientSettings()
    ),
    model = BedrockModels.Embeddings.AmazonTitanEmbedText
)

LLMEmbedder.embed(text) 返回 ai.koog.embeddings.base.Vector,不是原始的 List<Double>;这个类在 1.3.0 中没有 embedBatch 方法。批量接口位于客户端层:LLMEmbeddingProvider.embed(inputs: List<String>, model) 返回 List<List<Double>>,单条重载返回 List<Double>。两层 API 不要混用。

LLMEmbedder.diff(a, b) 接收两个 Vector,在本地计算 1 - 余弦相似度,不会请求模型;这只是该实现的度量,不能据此认定任意自定义 Embedder.diff 都是余弦距离。

1.2 模型怎么选

下表列出 Koog 的 OllamaModels.Embeddings 常量。上下文列采用 Koog 1.3.0 中的 contextLength 声明值,不是对所有服务端模型版本的上限承诺;实际输入上限应核对部署的模型。

常量 模型 ID 常见输出维度 Koog 声明的上下文 用途
NOMIC_EMBED_TEXT nomic-embed-text 768 2048 通用文本嵌入
ALL_MINI_LM all-minilm 384 512 轻量文本嵌入
MULTILINGUAL_E5 zylonai/multilingual-e5-large 1024 512 多语言检索
BGE_LARGE bge-large 1024 512 英文检索

官网与源码注释把 MULTILINGUAL_E5 的维度列成了 768,但这个常量指向的是 multilingual-e5-large,其模型配置为 1024 维。这里以实际模型配置为准;本文没有本地 Ollama,未实测这些模型的返回向量长度,也没有对它们做质量排名。

云端的 TextEmbeddingAda002 和 Amazon Titan 系列同理,按维度、费用、语言覆盖选。

1.3 DeepSeek 不支持——实测

这是本篇第一个要钉死的坑。本篇使用的 Koog DeepSeek 客户端里,嵌入方法是无条件抛异常的:

/** Embedding is not supported by the DeepSeek API.
 *  @throws UnsupportedOperationException Always thrown. */
override suspend fun embed(text: String, model: LLModel): List<Double> {
    throw UnsupportedOperationException("Embedding is not supported by DeepSeek API.")
}

单条和批量两个重载都如此(1.3.0-beta sources 原文),并且实测确认:runCatching { deepSeekClient.embed(...) } 拿到的就是 UnsupportedOperationException。原因不在 Koog——DeepSeek API 本身没有嵌入端点。

所以不能把 DeepSeek 客户端直接接入 LLMEmbedder 来生成向量;但聊天使用 DeepSeek,不妨碍嵌入使用其他实现。可选项:嵌入用 Ollama 本地模型或 OpenAI/Bedrock 云端(引入第二个 provider),或者跳过向量嵌入、用下一节的本地检索存储。本文示例采用后者的组合:聊天交给 DeepSeek,检索用不依赖嵌入的本地实现。

二、检索的抽象层:rag-base

2.1 抽象与请求类型

rag-base(1.3.0 正式版)定义了存储的两半:SearchStorage(查询)和 WriteStorage(写入),以及三种搜索请求——KeywordSearchRequest(关键词)、SimilaritySearchRequest(相似度)、HybridSearchRequest(混合)。存储实现方决定每种请求的具体语义。

下面用实现了这些接口的 InMemoryRecordStorage 观察请求语义。它不在 rag-base,而在 agents-features-longterm-memory:1.3.0-beta(包 ai.koog.agents.longtermmemory.storage),适合 LongTermMemory 的测试和原型。它不生成向量,数据仅留在当前进程的内存中,重启即丢失。

2.2 实测:两种请求的真实语义

下面是完整程序,不调用任何模型:

import ai.koog.agents.longtermmemory.model.MemoryRecord
import ai.koog.agents.longtermmemory.storage.InMemoryRecordStorage
import ai.koog.rag.base.storage.search.KeywordSearchRequest
import ai.koog.rag.base.storage.search.SimilaritySearchRequest
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val storage = InMemoryRecordStorage()

    val faqs = listOf(
        MemoryRecord(id = "faq-refund", content = "退款政策:课程购买后 7 天内可无理由全额退款,退款将原路退回支付账户;超过 7 天需联系人工客服评估处理。"),
        MemoryRecord(id = "faq-invoice", content = "发票政策:所有订单支持开具电子普通发票,可在订单详情页自助申请,1-3 个工作日内发送到邮箱。"),
        MemoryRecord(id = "faq-refund-en", content = "Our refund policy allows a full refund within 7 days of purchase."),
        MemoryRecord(id = "faq-membership", content = "会员权益:Pro 会员每月包含 1000 次模型调用额度,未用完的额度不累积到下月。"),
    )
    val ids = storage.add(faqs)
    println("写入 ${ids.size} 条,storage.size() = ${storage.size()}")

    // 关键词:大小写不敏感子串匹配
    val keywordResults = storage.search(KeywordSearchRequest(queryText = "Refund", limit = 10), null)
    keywordResults.forEach { result ->
        val record = result.document as MemoryRecord
        println("[keyword] [${record.id}] score=${result.score.value} :: ${record.content.take(40)}…")
    }

    // 相似度:大小写不敏感词集上的 Jaccard 系数(无向量嵌入)
    val similarityResults = storage.search(
        SimilaritySearchRequest(queryText = "full refund within 7 days", limit = 3, minScore = 0.1),
        null
    )
    similarityResults.forEach { result ->
        val record = result.document as MemoryRecord
        println("[similarity] [${record.id}] score=${"%.4f".format(result.score.value)} :: ${record.content.take(40)}…")
    }
}

真实运行输出:

写入 4 条,storage.size() = 4
[keyword] [faq-refund-en] score=1.0 :: Our refund policy allows a full refund w…
[similarity] [faq-refund-en] score=0.4545 :: Our refund policy allows a full refund w…
[similarity] [faq-refund] score=0.2000 :: 退款政策:课程购买后 7 天内可无理由全额退款,退款将原路退回支付账户;超过 7…

三个值得记住的实现细节(sources 确认 + 实测):

  1. 关键词检索是"大小写不敏感子串匹配",命中即固定 Score(1.0)。Score 的 metric 标签写着 COSINE_SIMILARITY,但这是枚举占位——子串匹配和余弦相似度没有任何关系,别被字段名误导。
  2. 相似度检索是 Jaccard 系数:按 Regex("\\W+") 切词、忽略大小写,对词集求交并比。在本文的 JVM 环境中,未启用 Unicode 字符类的 \w 不包含中文,中文会被当作分隔符,而不是“整句保留成一个词”。英文查询有 5 个 token,与英文 FAQ 的交集为 5、并集为 11,得 0.4545。中文退款条目切词后实际只剩 {7},与查询交集为 1、并集为 5,才得到 0.2000;这不是理解了退款语义。纯中文且不含 ASCII 字母或数字的相同文本,甚至可能得到 0 分并被过滤。第五章的 LongTermMemory 示例因此采用英文;中文可先用关键词子串检索,或更换分词/检索实现,并不一定要用向量库。
  3. filterExpression 被忽略;关键词路径还会忽略 offset,相似度路径才应用它。非空 namespace 在这个实现中会分桶存储,但它不是权限检查。存储不支持的请求类型(如混合请求)抛 UnsupportedOperationException。不要把过滤表达式当作租户授权条件。

2.3 自己接向量库的起点

rag-base 的定位是抽象层:要接 Pinecone、pgvector、Weaviate 这类生产向量库,官方建议从这里入手,实现 SearchStorage + WriteStorage 两个接口,把 search、add、update 翻译成后端调用。3.3 会汇总当前内置实现的差距。

三、rag-vector:文档嵌入存储(beta)

3.1 组合模式

rag-vector(beta)提供"文档 → 向量 → 存储"的开箱组合。核心类 EmbeddingStorage 把两个组件拼起来:DocumentEmbedder(文档转向量)+ VectorStorageBackend(保存文档和向量,是否持久化取决于后端)。官方五步流程(1.3.0-beta 下编译验证通过):

import ai.koog.embeddings.local.LLMEmbedder
import ai.koog.prompt.executor.ollama.client.OllamaClient
import ai.koog.prompt.executor.ollama.client.OllamaModels
import ai.koog.rag.vector.backend.InMemoryVectorStorageBackend
import ai.koog.rag.vector.embedder.JVMTextDocumentEmbedder
import ai.koog.rag.vector.storage.EmbeddingStorage
import ai.koog.rag.base.storage.search.SimilaritySearchRequest
import java.nio.file.Path

// 1. 嵌入器(需要真实 Ollama 或云端服务才能完成 embed)
val embedder = LLMEmbedder(OllamaClient(), OllamaModels.Embeddings.NOMIC_EMBED_TEXT)

// 2. JVM 文档嵌入器:读文件内容并委托给 embedder
val documentEmbedder = JVMTextDocumentEmbedder(embedder)

// 3. 组合存储:内存后端
val storage = EmbeddingStorage(
    embedder = documentEmbedder,
    storage = InMemoryVectorStorageBackend(),
)

// 4. 添加文档(Path 文档)
// storage.add(listOf(Path.of("./docs/faq.txt"), Path.of("./docs/pricing.txt")))

// 5. 相似度检索
// val results = storage.search(SimilaritySearchRequest(queryText = "How do I reset my password?", limit = 3, minScore = 0.5))

add 和 search 会真实调用嵌入服务,所以这两步在本文里保持注释状态(本机没有 Ollama,DeepSeek 又不支持嵌入);构造与类型在 beta 依赖下全部编译通过。

EmbeddingStorage<Document> 实现的是 SearchStorage<Document, SimilaritySearchRequest>:请求类型已经由泛型限定,直接传 KeywordSearchRequest 会编译失败,而不是运行时抛 IllegalArgumentException。非空 namespace 或非空 filterExpression 才由运行时检查拒绝,并抛 IllegalArgumentException;这些能力不能从 rag-base 的请求字段反推实现已支持。

它会遍历后端里的文档向量,按 1 - embedder.diff 打分、排序和分页。本例接入 LLMEmbedder,所以结果是余弦相似度;换成自定义 embedder 后要重新核对度量。它并不自带近似最近邻索引,和第二章的 Jaccard 也不是同一种分数。

3.2 实现清单

类别 实现 说明
向量后端 InMemoryVectorStorageBackend 内存,测试与原型
FileVectorStorageBackend / JVMFileVectorStorageBackend 磁盘持久化,跨重启
文档嵌入器 DocumentEmbedder<Document> 文档嵌入接口
TextDocumentEmbedder<Document, Path> 通过 DocumentProvider 读取文本并调用 Embedder
JVMTextDocumentEmbedder 从 java.nio.file.Path 读文件
组合存储 EmbeddingStorage 任意 embedder + 任意 backend
InMemoryDocumentEmbeddingStorage / InMemoryTextDocumentEmbeddingStorage 内存组合的简写
FileDocumentEmbeddingStorage / TextFileDocumentEmbeddingStorage 通用文件组合
JVMFileDocumentEmbeddingStorage / JVMFileEmbeddingStorage JVM 文件组合

3.3 当前限制(官方明示)

内置实现是本地原型,不是生产 RAG 平台:只支持相似度检索、没有内置 chunking(长文档不会自动切块)、记录元数据建模有限、没有 Pinecone/Weaviate/pgvector/Milvus 集成。生产化路径 = rag-base 抽象 + 自研后端适配器,向量嵌入可继续用 LLMEmbedder。

四、Agent 里的 RAG:把检索做成工具

4.1 两种接法

检索结果进入 agent 有两种方式:预先检索、把文档拼进 prompt;或者把检索暴露成工具,让模型自己决定何时查、查什么。后者就是 agentic RAG——对"只有部分请求需要查知识库"的场景更合适,也正好复用第四篇的工具体系。

4.2 实测:真实 DeepSeek + 本地知识库

下面直接给出完整程序。存储仍是 2.2 的 InMemoryRecordStorage,但种子数据改成退款、发票、会员权益、技术支持四条 FAQ,没有英文退款条目。所有政策均为虚构示例,与 Koog 的服务政策无关。工具先去掉查询首尾空白,拒绝空查询和超过 200 字符的查询,把条数限制在 1—10;合并时关键词命中优先,再补 Jaccard 结果,并标注 method/rawScore,不能跨算法比较两个分数。

该程序会实际请求 DeepSeek,需要替换占位凭据;executor 由本程序创建,因此在 finally 中显式关闭:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.core.tools.annotations.LLMDescription
import ai.koog.agents.core.tools.annotations.Tool
import ai.koog.agents.core.tools.reflect.asTool
import ai.koog.agents.longtermmemory.model.MemoryRecord
import ai.koog.agents.longtermmemory.storage.InMemoryRecordStorage
import ai.koog.prompt.executor.clients.deepseek.DeepSeekLLMClient
import ai.koog.prompt.executor.clients.deepseek.DeepSeekModels
import ai.koog.prompt.executor.llms.MultiLLMPromptExecutor
import ai.koog.rag.base.storage.search.KeywordSearchRequest
import ai.koog.rag.base.storage.search.SimilaritySearchRequest
import kotlinx.coroutines.runBlocking

private val faqStorage = InMemoryRecordStorage()
private val toolHits = mutableListOf<String>()

// 四条虚构 FAQ:退款、发票、会员权益、技术支持;不是 Koog 的服务政策。
private suspend fun seedFaqStorage() {
    faqStorage.add(
        listOf(
            MemoryRecord(id = "faq-refund", content = "退款政策:课程购买后 7 天内可无理由全额退款,退款将原路退回支付账户;超过 7 天需联系人工客服评估处理。"),
            MemoryRecord(id = "faq-invoice", content = "发票政策:所有订单支持开具电子普通发票,可在订单详情页自助申请,1-3 个工作日内发送到邮箱。"),
            MemoryRecord(id = "faq-membership", content = "会员权益:Pro 会员每月包含 1000 次模型调用额度,未用完的额度不累积到下月。"),
            MemoryRecord(id = "faq-support", content = "技术支持:工作日 9:00-18:00 提供在线客服支持,紧急问题可提交工单,平均响应时间 2 小时。"),
        )
    )
}

@Tool
@LLMDescription("在本地 FAQ 知识库中检索政策条目(退款/发票/会员/技术支持)。回答此类问题前必须先调用本工具。")
suspend fun searchFaq(
    @LLMDescription("检索查询词,建议使用简短关键词,例如:退款、发票、会员、技术支持")
    query: String,
    @LLMDescription("最多返回的条目数,默认 3")
    count: Int = 3,
): String {
    val cleanQuery = query.trim()
    if (cleanQuery.isEmpty()) return "检索词不能为空,请提供退款、发票等关键词。"
    if (cleanQuery.length > 200) return "检索词过长,请限制在 200 个字符以内。"
    val limit = count.coerceIn(1, 10)
    toolHits += "searchFaq(query=\"$query\", count=$count)"

    // 关键词命中优先,再补 Jaccard 结果;两种分数不作统一排序。
    val merged = buildList {
        faqStorage.search(KeywordSearchRequest(queryText = cleanQuery, limit = limit), null)
            .forEach { add("keyword-substring" to it) }
        faqStorage.search(SimilaritySearchRequest(queryText = cleanQuery, limit = limit), null).forEach { sim ->
            if (none { it.second.document.id == sim.document.id }) add("jaccard" to sim)
        }
    }.take(limit)

    if (merged.isEmpty()) return "知识库中没有找到与「$query」相关的条目。"
    return buildString {
        appendLine("在知识库中找到 ${merged.size} 条与「$query」相关的 FAQ:")
        merged.forEach { (method, result) ->
            val record = result.document as MemoryRecord
            appendLine("[${record.id}] method=$method rawScore=${"%.3f".format(result.score.value)} :: ${record.content}")
        }
    }
}

fun main() = runBlocking {
    seedFaqStorage()
    println("知识库已就绪,共 ${faqStorage.size()} 条 FAQ。")
    val executor = MultiLLMPromptExecutor(DeepSeekLLMClient(apiKey = "xxxxxxx"))
    val agent = AIAgent(
        promptExecutor = executor,
        llmModel = DeepSeekModels.DeepSeekV4Flash,
        systemPrompt = "你是课程平台的客服助手。凡是涉及退款、发票、会员权益、技术支持等政策类问题,必须先调用 searchFaq 工具检索知识库,再根据检索结果回答;不要编造政策细节。",
        temperature = 0.3,
        toolRegistry = ToolRegistry { tool(::searchFaq.asTool()) },
        maxIterations = 10,
    )
    val question = "我想把上周买的课程退掉,你们的退款政策是怎样的?超过 7 天还能退吗?"
    try {
        println("用户问题:$question")
        val answer = agent.run(question)
        println("=== Agent 回答 ===")
        println(answer)
        println("=== 工具命中记录(${toolHits.size} 次调用) ===")
        toolHits.forEachIndexed { index, hit -> println("  ${index + 1}. $hit") }
    } finally {
        try { agent.close() } finally { executor.close() }
    }
    Unit
}

下面保留此前真实 DeepSeek 运行的节选,省略框架日志和部分回答段落;不是本次离线检查新生成的模型输出。当前代码已补齐对应的打印与命中记录,展示顺序也与程序一致。再次运行时,调用次数、参数和措辞可能变化:

用户问题:我想把上周买的课程退掉,你们的退款政策是怎样的?超过 7 天还能退吗?
=== Agent 回答 ===
根据知识库中的退款政策(faq-refund),情况是这样的:

**退款政策要点**
- **购买后 7 天内**:可无理由全额退款,款项将原路退回支付账户。
- **超过 7 天**:不在自助退款范围内,需联系人工客服评估处理。

=== 工具命中记录(2 次调用) ===
  1. searchFaq(query="退款", count=5)
  2. searchFaq(query="退款期限 7天", count=5)

这次运行确实调用了工具,但不能据此说回答“每条都来自知识库、没有编造”。原始回答还补充了“自助退款范围”“以支付成功时间为准”和到账时间等知识库没有明说的细节。这正是 RAG 需要逐项核对证据的原因:检索提供参考,不保证模型不发挥。

system prompt 和工具描述里的“必须先调用”也只是模型指令,不是程序控制。如果业务要求每个政策回答都先查库,应把检索放进固定策略节点,再校验输出中的政策与引用。把知识内容视为不可信数据,不允许其中的指令覆盖系统规则;订单查询、转人工等能力只有在实际接入工具后才能向用户承诺。工具化适合按需检索,但不天然比预检索更可靠。

一个移植提醒:官方 agentic RAG 示例里 result.document 被当作 Path(Files.readString(result.document))——那只对 rag-vector 的文件文档成立。用 InMemoryRecordStorage 时 document 是 TextDocument,直接取 result.document.content。两种存储混用时别照抄。

五、LongTermMemory(beta)

5.1 两组独立配置

LongTermMemory 是把 RAG 能力 feature 化:retrieval(每次 LLM 调用前检索、增强 prompt)和 ingestion(agent 运行完成时把会话消息写入存储)两组配置相互独立,可以只用其一。

import ai.koog.agents.longtermmemory.feature.LongTermMemory
import ai.koog.agents.longtermmemory.retrieval.search.SimilaritySearchStrategy

// AIAgent 安装块内的配置片段;myStorage 是已创建的存储对象。
install(LongTermMemory) {
    retrieval {
        storage = myStorage
        searchStrategy = SimilaritySearchStrategy(topK = 3)
    }
    ingestion {
        storage = myStorage
    }
}

每个显式配置的 retrieval 或 ingestion 块内部,storage 都是必填项;整块可以不配置,从而只启用另一侧。import 路径是 ai.koog.agents.longtermmemory.feature.LongTermMemory——注意与第 6 篇其他 feature 的包惯例不同。

5.2 retrieval 的可配项

配置 默认 说明
searchStrategy SimilaritySearchStrategy(topK = 10, similarityThreshold = 0.0) 相似度检索;也可传 lambda 自定义
searchQueryProvider LastUserMessageQueryProvider 用最后一条 user 消息当查询;可传 lambda 自定义
promptAugmenter SystemPromptAugmenter 检索结果怎么注入 prompt
namespace null 传给后端的逻辑分桶名;隔离能力取决于后端
failurePolicy FAIL_FAST 检索失败是否中断

增强器三选一:

增强器 行为
SystemPromptAugmenter 将检索上下文作为新文本 part 追加到第一条 system 消息末尾;prompt 没有 system 消息时是静默 no-op
UserPromptAugmenter 追加到最后一条 user 消息末尾
PromptAugmenter { prompt, context -> … } 自定义 lambda,可加日志、改写

实测踩到的坑:默认的 SystemPromptAugmenter 依赖 prompt 里存在 system 消息。如果 agent 用 Prompt.Empty 这类没有 system 消息的配置,检索照常执行、结果却哪里都不去——增强静默失效。要么给 agent 配 systemPrompt,要么显式换 UserPromptAugmenter。我们的示例用了自定义 PromptAugmenter,顺带把每次命中打印出来当验证证据。

还有两个时序事实:检索发生在每次 LLM 调用前(流式同理);run(input, sessionId) 的 sessionId 用作 runId,也会被 ChatMemory 等机制使用,但 LongTermMemory 不会据此自动分桶;它把独立配置的 namespace 传给后端——这和第六篇 2.2 的会话分桶是两套机制。检索和入库两侧应分别配置成同一业务分桶;共享默认 namespace 会允许跨 session 检索,不能当作用户私有记忆。

5.3 ingestion:运行结束才落库

ingestion 在 interceptAgentCompleted 时,把最终 prompt 中的消息一次性批量交给 DocumentExtractor。默认 MessagePassingDocumentExtractor 只提取 User 和 Assistant;自定义提取器可以做摘要或只保留指定角色。failurePolicy = LOG_AND_CONTINUE 默认只处理存储 add 的普通异常:提取器在这个保护范围之外,异常仍会传播;取消异常也不会被吞掉。

自动 ingestion 挂在 agent 完成点上:策略在中途抛错、没有到达完成点,就不会触发这次自动写入;但不能推导成“任何失败都零写入”。存储的批量 add 未必有事务性,写一部分再失败时不会由 LTM 自动回滚,策略中的手动写入也不受这个完成点约束。

ingestion 的粒度是“最终 prompt 里的消息”,不是逐轮增量;配合 ChatMemory 时可能重复收录旧历史,应自行去重。

5.4 三种模式与手动访问

enableAutomaticRetrieval / enableAutomaticIngestion 两个开关组合出三种模式:全自动(配置对应 storage 后,两个开关默认开启)、纯手动(都关掉,在策略节点里自己调存储)、混合(如自动入库 + 手动检索)。手动访问的入口:

import ai.koog.agents.core.dsl.builder.*
import ai.koog.agents.longtermmemory.feature.withLongTermMemory
import ai.koog.agents.longtermmemory.model.MemoryRecord
import ai.koog.rag.base.storage.search.SimilaritySearchRequest

// 策略声明;运行它的 agent 必须已安装 LongTermMemory 并配置对应 storage。
val manualMemoryStrategy = strategy<String, Unit>("manual-memory") {
    val myNode by node<String, Unit> { input ->
        withLongTermMemory {
            ingestionStorage?.add(listOf(MemoryRecord(content = "important fact")), namespace = "my-namespace")
            val results = retrievalStorage?.search(
                SimilaritySearchRequest(queryText = input, limit = 5),
                namespace = "my-namespace",
            )
            println("manual retrieval count=${results?.size ?: 0}")
        }
    }
    edge(nodeStart forwardTo myNode)
    edge(myNode forwardTo nodeFinish)
}

longTermMemory() 则直接拿 feature 实例。

5.5 实测:两次 run 之间发生了什么

这个实验使用真实 DeepSeek + InMemoryRecordStorage:同一个 agent 两次 run,第一次输入人为设定的事实,第二次提问。Nebula Comet 是实验虚构代号,不是 Koog 1.3 的官方代号。 程序没有安装 ChatMemory;固定 sessionId 本身不会自动续聊。

检索日志用于观察“写入 → 检索 → 增强”的链路,但一次正确回答不能证明增强是唯一原因,更不能证明模型此前绝不可能生成同一词组。严格评估还要使用随机事实、空存储或关闭 retrieval 的对照,并检查模型真正收到的 prompt。

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.longtermmemory.feature.LongTermMemory
import ai.koog.agents.longtermmemory.retrieval.augmentation.PromptAugmenter
import ai.koog.agents.longtermmemory.retrieval.augmentation.UserPromptAugmenter
import ai.koog.agents.longtermmemory.retrieval.search.SimilaritySearchStrategy
import ai.koog.agents.longtermmemory.storage.InMemoryRecordStorage
import ai.koog.prompt.executor.clients.deepseek.DeepSeekLLMClient
import ai.koog.prompt.executor.clients.deepseek.DeepSeekModels
import ai.koog.prompt.executor.llms.MultiLLMPromptExecutor
import kotlinx.coroutines.runBlocking

val memoryStorage = InMemoryRecordStorage()

val executor = MultiLLMPromptExecutor(DeepSeekLLMClient(apiKey = "xxxxxxx"))
val agent = AIAgent(
    promptExecutor = executor,
    llmModel = DeepSeekModels.DeepSeekV4Flash,
    systemPrompt = "You are a helpful assistant. Relevant long-term memories may be injected into your prompt automatically.",
    temperature = 0.2,
    toolRegistry = ToolRegistry.EMPTY,
) {
    install(LongTermMemory) {
        retrieval {
            storage = memoryStorage
            searchStrategy = SimilaritySearchStrategy(topK = 3)
            promptAugmenter = PromptAugmenter { originalPrompt, relevantContext ->
                println("[LTM retrieval] 本次 LLM 调用前检索命中 ${relevantContext.size} 条记录:")
                relevantContext.forEach { result ->
                    println("[LTM retrieval]   score=${"%.3f".format(result.score.value)} :: ${result.document.content.take(70)}")
                }
                UserPromptAugmenter().augment(originalPrompt, relevantContext)
            }
        }
        ingestion { storage = memoryStorage }
    }
}

val sessionId = "ltm-demo-session"
// Nebula Comet 是实验中人为设定的虚构代号,不是 Koog 的官方发布信息。
// 未安装 ChatMemory;固定 sessionId 并不会为 LongTermMemory 自动分桶。
fun main() = runBlocking {
    try {
        println("=== 第一次 run:告诉一个事实(sessionId=$sessionId) ===")
        val first = agent.run(
            "Please remember this fact: the release codename of Koog 1.3 is Nebula Comet.",
            sessionId = sessionId,
        )
        println("[run1] agent 回答:$first")
        println("[run1] ingestion 完成,memoryStorage.size() = ${memoryStorage.size()}")
        println()
        println("=== 第二次 run:同一 agent 提问(同一 sessionId,无 ChatMemory 续聊) ===")
        val second = agent.run("What is the release codename of Koog 1.3?", sessionId = sessionId)
        println("[run2] agent 回答:$second")
        println("[run2] memoryStorage.size() = ${memoryStorage.size()}")
    } finally {
        try { agent.close() } finally { executor.close() }
    }
    Unit
}

下面保留此前真实 DeepSeek 运行的日志节选,省略框架日志;本轮只重新编译,未再次请求模型。代码已补齐对应打印,再次运行时回答和检索分数可能变化:

=== 第一次 run:告诉一个事实(sessionId=ltm-demo-session) ===
[run1] agent 回答:Got it — I'll remember that the release codename of Koog 1.3 is **Nebula Comet**.
[run1] ingestion 完成,memoryStorage.size() = 2

=== 第二次 run:同一 agent 提问(同一 sessionId,无 ChatMemory 续聊) ===
[LTM retrieval] 本次 LLM 调用前检索命中 2 条记录:
[LTM retrieval]   score=0.533 :: Please remember this fact: the release codename of Koog 1.3 is Nebula 
[LTM retrieval]   score=0.471 :: Got it — I'll remember that the release codename of Koog 1.3 is **Nebu
[run2] agent 回答:The release codename of Koog 1.3 is **Nebula Comet**.
[run2] memoryStorage.size() = 4

这次日志中,run1 结束时 ingestion 把 user 消息和 assistant 确认写进存储(size=2);run2 的 LLM 调用前,retrieval 用 "What is the release codename of Koog 1.3?" 做查询,Jaccard 命中两条历史记录(0.533/0.471),增强进 prompt 后模型答出 Nebula Comet。size 最终到 4 是因为 run2 的问答也被 ingestion 收走了——内存存储在同一进程内持续累积,不代表重启后仍能恢复。

事实和提问使用英文,并刻意保留词汇重叠,是为了适配这个存储的 Jaccard 实现;这不是向量语义检索效果评估。中文可改用关键词 SearchStrategy、自定义中文分词,或采用真正的嵌入存储,不必一律换向量库。还要注意:增强过的 User/System 文本可能留在当前 run 的 prompt 中;多次 LLM 调用可能重复增强,默认 ingestion 也可能把增强后的 user 文本再次入库。生产实现应控制重复注入、去重、来源与保留期限。

5.6 接入真实向量库

生产用法是实现 SearchStorage + WriteStorage(rag-base 接口),把检索与写入翻译成向量库调用,替换掉 InMemoryRecordStorage:

import ai.koog.rag.base.TextDocument
import ai.koog.rag.base.storage.SearchStorage
import ai.koog.rag.base.storage.WriteStorage
import ai.koog.rag.base.storage.search.SearchRequest
import ai.koog.rag.base.storage.search.SearchResult

// 可编译的接口骨架,不是可直接连接数据库的驱动。
// 保持 abstract,具体实现必须补齐这三个操作。
abstract class MyVectorDbStorage :
    SearchStorage<TextDocument, SearchRequest>,
    WriteStorage<TextDocument> {
    abstract override suspend fun search(
        request: SearchRequest,
        namespace: String?,
    ): List<SearchResult<TextDocument>>

    abstract override suspend fun add(
        documents: List<TextDocument>,
        namespace: String?,
    ): List<String>

    abstract override suspend fun update(
        documents: Map<String, TextDocument>,
        namespace: String?,
    ): List<String>
}

LongTermMemory 的配置结构不变——retrieval/ingestion 的 storage 换成你的实现即可。这只是接口契约,尚未实现连接、索引、查询与写入,不能实例化这个抽象类冒充可用驱动。实现时要明确支持哪些请求、分数度量、分页、metadata 过滤和 namespace,并在服务端执行用户授权。嵌入部分可以继续用 LLMEmbedder(1.1),也可以在适配器内部调向量库自带的嵌入服务。

六、选型与落地

6.1 内置 vs 自建

官方的边界画得很清楚:rag-vector 适合本地原型、参考实现和体验流程;生产化从 rag-base 抽象 + 自研后端开始。差距清单(官方"当前限制"+ 本文实测):

  • rag-vector 的 EmbeddingStorage 只接收相似度请求,没有内置混合检索与重排;InMemoryRecordStorage 则另外支持关键词请求
  • 无内置 chunking,长文档不会自动切块
  • 元数据建模有限(MemoryRecord 只有 content/id/metadata 三属性)
  • 无生产向量库集成
  • InMemoryRecordStorage 的 JVM Jaccard 切词不适合中文;关键词子串匹配仍可用于中文原型(2.2)
  • 不能用 DeepSeek 客户端生成嵌入;向量路线需另配嵌入实现或已有向量的检索服务(1.3)

6.2 与 ChatMemory 的分工

第 6 篇的 ChatMemory 和本篇的 LongTermMemory 解决不同问题:前者存"对话历史"(本轮消息序列,按 sessionId 分桶,每轮读写),后者存"知识"(跨会话、按 namespace 隔离、检索式读取)。第六篇 5.x 提到的 LongTermMemory beta 小节只展示了安装;现在可以补全对比——ChatMemory 回答"上次聊到哪了",LongTermMemory 在接入持久化存储、正确分桶并设置保留策略后,才有条件检索更早的事实;本篇内存示例不能保存到应用重启之后。两者可以同时安装,但不是完全互不影响:ChatMemory 恢复的历史可能再次进入 LTM ingestion,增强后的文本也可能进入历史存储。需要明确写入范围、去重与隐私边界,不能把 namespace 或 sessionId 当成授权机制。

6.3 给 DeepSeek 用户的最小组合

综合本篇实测,DeepSeek 用户落地知识增强的最小可行组合:

  1. 聊天:DeepSeek(正常调用)。
  2. 检索:InMemoryRecordStorage 起步,中文内容用 KeywordSearchRequest(子串匹配对中文有效),或直接上自定义向量库适配器。
  3. 嵌入:需要向量检索时,用 Ollama 本地模型或 OpenAI/Bedrock,嵌入与聊天分开计费与部署。
  4. 临时不要把 InMemoryRecordStorage 的 Jaccard 分数当语义相关性——它只是词集重叠率。

后记

一张表收束本篇:

能力 版本 一句话记住
LLMEmbedder 1.3.0 三种 provider 构造;DeepSeek 抛 UnsupportedOperationException
rag-base 1.3.0 SearchStorage/WriteStorage 抽象;InMemoryRecordStorage 在 LTM 模块
rag-vector beta EmbeddingStorage 组合模式;无 chunking、仅相似度
agentic RAG 组合 检索做成 @Tool;document 类型随存储而异
LongTermMemory beta retrieval 每次调用前增强、ingestion 完成时落库;SystemPromptAugmenter 会静默 no-op

下一篇是本系列的收官:生态集成——Ktor/Spring Boot 后端集成、MCP 工具接入,以及 A2A 协议。

参考资料

posted @ 2026-10-20 20:52  SharpCJ  阅读(26)  评论(0)    收藏  举报