rungent v0.5.1
EN中文

rungent核心概念

搜索与知识

一次搜索覆盖你自己的搜索接口和你的文档。用户在 ⌘K 里用它,Agent 在作答前用它搜索,每个回答都会引用它用到的结果。

⌘K 搜索面板正在搜索 gpu
来自控制台搜索接口的服务器和一页文档,合并成一个列表。最后一行把搜索词交给助手;没有及时响应的来源列在底部。

⌘K 搜索面板、Agent 的 search 工具、MCP 和 CLI(acme search "gpu")用的是同一个搜索。你的每个 role: search 操作都是一个来源;由 rungent 建好索引的文档是另一个来源,名叫 knowledge。

添加搜索来源#

搜索来源是一个 GET,带必填的 q 查询参数和可选的 limit:

"/api/vms/search": { "get": { "x-rungent": { "name": "search_vms", "role": "search" } } }

GET /api/vms/search?q=gpu&limit=10 按相关度从高到低返回结果:

{
  "hits": [
    { "type": "vm", "id": "vm-42", "title": "gpu-train-01", "excerpt": "Running · 8 × «H100» · cn-beijing-a",
      "url": "/console/instance/vm-42", "updatedAt": "2026-11-19T08:00:00Z" }
  ]
}
字段 含义
type 必填。简短的类别(vm、doc),用于分组和筛选。
id 必填。在同一类别内唯一。
title 必填。
url 必填。产品内的路径,或绝对 URL。
excerpt 纯文本,最多 300 个字符;匹配的部分可以用 «…» 包起来。
updatedAt RFC 3339 时间。
content 段落原文,最多 4000 个字符,只给模型看,用户永远看不到。

rungent 以用户身份调用每个来源,所以你的权限检查已经过滤好了结果。limit 默认 10,最大 50。

一次搜索覆盖所有来源#

rungent 同时询问所有来源,每个来源有自己的超时(默认 2 秒,最多 10 秒,用 timeoutSeconds 设置),再用倒数排名融合(reciprocal rank fusion)合并列表:一条结果的位置取决于各来源给它的排名,所以各来源的分数不需要可比。超时或出错的来源会列在 failed 里,其他来源照常返回。

添加你的文档#

用 rungent serve 时,两个环境变量就能在启动时为一个 Markdown 文件夹建索引:

RUNGENT_KNOWLEDGE_DIR=/srv/docs
RUNGENT_KNOWLEDGE_BASE_URL=https://docs.acme.example.com

文件夹下的每个 .md 和 .mdx 文件都成为一个页面。页面地址是基础 URL 加上去掉扩展名的路径(deploy/certificates.md 变成 …/deploy/certificates,index 文件代表所在文件夹);标题取 frontmatter 的 title,没有就取第一个标题。未改动的页面会跳过,所以重启的代价很小。基础 URL 也可以是你产品上的一个路径(/help)。

在代码里为文档建索引#

嵌入式部署,或者要决定谁能看到哪些文档时,用 rungent/knowledge。它跑在 Postgres、SQLite 或 D1 上,可以和 rungent 共用数据库:它的表都以 rungent_knowledge_ 开头。

import { readFile } from 'node:fs/promises';
import { createKnowledge } from 'rungent/knowledge';
import { postgresDriver } from 'rungent/sql/postgres';

const knowledge = createKnowledge({ driver: postgresDriver(process.env.DATABASE_URL!) });
await knowledge.migrate();

await knowledge.ingest('docs', [
  {
    id: 'deploy/certificates',
    title: 'Rotate certificates',
    url: '/help/deploy/certificates',
    markdown: await readFile('docs/deploy/certificates.md', 'utf8'),
  },
]);

const rungent = createRungent({
  // ...
  sources: [knowledge.source({ collections: (identity) => ['docs', `manuals/${identity.tenant}`] })],
});
  • ingest(collection, documents) 添加或替换文档,返回 { updated, unchanged }。每次构建文档后运行它;未改动的文档会跳过,文字没变的章节保留原有的 embedding。remove(collection, ids) 删除你的来源里已经没有的文档。
  • collections 接收用户的身份,挑出这个用户能搜索的范围,所以某个租户的私有手册只留在这个租户内。这个来源名叫 knowledge;传 name 可以改名。
  • embed 和 dimensions 加上按语义搜索(搜「cert expiry」能找到「Rotate certificates」),可以用任何 embedding 服务:
const knowledge = createKnowledge({
  driver,
  embed: async (texts) =>
    (await openai.embeddings.create({ model: 'text-embedding-3-small', input: texts })).data.map((d) => d.embedding),
  dimensions: 1536,
});

没有 embedder 时,搜索只按词匹配,中文也支持。向量搜索每次查询最多读取被搜索集合中最新的 20,000 个章节。

写出便于引用的文档#

rungent 按 h1 到 h3 标题切分每个页面,超过约 800 token 的章节再按段落切开。一条结果的标题是 页面标题 › 小标题,链接是页面地址加上这个小标题的锚点。写文档时,让每个章节回答一个问题,并用标题点明这个问题。如果某个标题的锚点不能随措辞改变,就给它一个显式 id:

## Rotate certificates {#rotate}

依据与引用#

一个引用了来源的回答
cn-beijing-a 后面的数字标记链接到这句话所依据的结果。

有知识时,每条新的用户消息在模型第一步之前,都会先用它的文字搜索一次(取前 200 个字符,5 条结果)。这是对话里一次普通的 search 调用,所以用户能和其他查询一起看到它。模型被要求:关于你产品的问题只依据工具结果和搜索结果回答;结果答不上来时换个说法再搜;什么都没找到时如实说明。没有知识时,Agent 在需要找东西时搜索你的 role: search 操作。

search 工具在整个运行中从 1 开始给结果编号,并把它们的 content 交给模型。回答里引用 [1] 时,运行会发出一个 rungent.citation 事件,把每个编号对应到它的结果(不含 content),面板把它渲染成指向结果 url 的链接。

接下来#

入口把 ⌘K 搜索面板和助手面板、MCP、CLI 放在一起介绍。

供 Agent 读取: search.md编辑此页