知识库

在 Astreus 文档中了解知识库，获取用于构建智能体系统的设置指导、API 模式和实用示例。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

集成 RAG,支持文档处理与向量搜索

概述

知识库(Knowledge)系统提供检索增强生成(RAG)能力,使代理能够在响应中访问并利用外部文档。它会自动处理文档、创建向量嵌入,并支持相关信息的语义搜索。启用知识库的代理能够基于你的文档提供更准确、更贴合上下文的响应。

启用知识库

将 knowledge 选项设置为 true 即可为代理启用知识库:

import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'KnowledgeAgent',
  model: 'gpt-4o',
  knowledge: true,  // Enable knowledge base access (default: false)
  embeddingModel: 'text-embedding-3-small' // Optional: specify embedding model
});

添加文档

添加文本内容

直接以字符串形式添加内容:

await agent.addKnowledge(
  'Your important content here',
  'Document Title',
  { category: 'documentation' }
);

从文件添加

从支持的文件类型中添加内容:

// Add PDF file
await agent.addKnowledgeFromFile(
  '/path/to/document.pdf',
  { source: 'manual', version: '1.0' }
);

// Add text file
await agent.addKnowledgeFromFile('/path/to/notes.txt');

从目录添加

处理目录中所有受支持的文件:

await agent.addKnowledgeFromDirectory(
  '/path/to/docs',
  { project: 'documentation' }
);

支持的文件类型

文本文件:.txt、.md、.json
PDF 文件:.pdf(支持文本提取)

工作原理

知识库系统遵循一套精心设计的处理流程:

文档处理

文档会连同元数据一起存储并索引到知识库数据库中。

文本分块

内容会被切分为多个块(每块 1500 字符,重叠 300 字符),以实现最佳检索效果。

重叠部分确保了上下文的连续性: $\text{overlap ratio} = \frac{300}{1500} = 0.2 = 20\%$

这可以防止重要信息被切割在块的边界之间。

向量嵌入

每个块都会通过 OpenAI、Gemini 或 Ollama 的嵌入模型转换为向量嵌入。

常见的嵌入维度:

text-embedding-3-small:1536 维(OpenAI)
text-embedding-3-large:3072 维(OpenAI)
text-embedding-ada-002:1536 维(OpenAI)
text-embedding-004:768 维(Gemini)

也可以使用向量之间的欧几里得距离: $d(\vec{p}, \vec{q}) = \sqrt{\sum_{i=1}^{n}(p_i - q_i)^2}$

语义搜索

当代理接收到查询时,会使用余弦相似度搜索检索相关的文本块。

查询向量与文档向量之间的相似度计算方式为:

$\text{cosine similarity} = \cos(\theta) = \frac{\vec{A} \cdot \vec{B}}{||\vec{A}|| \cdot ||\vec{B}||} = \frac{\sum_{i=1}^{n} A_i B_i}{\sqrt{\sum_{i=1}^{n} A_i^2} \cdot \sqrt{\sum_{i=1}^{n} B_i^2}}$

其中:

$\vec{A}$ 是查询嵌入向量
$\vec{B}$ 是文档块嵌入向量
数值越高(越接近 1)表示相似度越高

上下文集成

检索到的信息会自动添加到代理的上下文中,以增强响应质量。

使用示例

以下是一个在代理中使用知识库的完整示例:

import { Agent } from '@astreus-ai/astreus';

// Create agent with knowledge enabled
const agent = await Agent.create({
  name: 'DocumentAssistant',
  model: 'gpt-4o',
  knowledge: true,
  embeddingModel: 'text-embedding-3-small', // Optional: specify embedding model
  systemPrompt: 'You are a helpful assistant with access to company documentation.'
});

// Add documentation
await agent.addKnowledgeFromFile('./company-handbook.pdf', {
  type: 'handbook',
  department: 'hr'
});

await agent.addKnowledge(`
Our API uses REST principles with JSON responses.
Authentication is done via Bearer tokens.
Rate limiting is 1000 requests per hour.
`, 'API Documentation', {
  type: 'api-docs',
  version: '2.0'
});

// Query with automatic knowledge retrieval
const response = await agent.ask('What is our API rate limit?');
console.log(response);
// The agent will automatically search the knowledge base and include relevant context

// Manual knowledge search
const results = await agent.searchKnowledge('API authentication', 5, 0.7);
results.forEach(result => {
  console.log(`Similarity: ${result.similarity}`);
  console.log(`Content: ${result.content}`);
});

管理知识库

可用方法

// List all documents with metadata
const documents = await agent.getKnowledgeDocuments();
// Returns: Array<{ id: string; title: string; created_at: string }>

// Delete specific document by ID (documentId is UUID string)
const success = await agent.deleteKnowledgeDocument(documentId);
// Returns: boolean indicating success

// Delete specific chunk by ID (chunkId is UUID string)
const success = await agent.deleteKnowledgeChunk(chunkId);
// Returns: boolean indicating success

// Clear all knowledge for this agent
await agent.clearKnowledge();
// Returns: void

// Search with custom parameters
const results = await agent.searchKnowledge(
  'search query',
  10,    // limit: max results (default: 5)
  0.8    // threshold: similarity threshold (0-1, default: 0.7)
);
// Returns: Array<{ content: string; metadata: MetadataObject; similarity: number }>

// Get relevant context for a query
const context = await agent.getKnowledgeContext(
  'query text',
  5      // limit: max chunks to include (default: 5)
);
// Returns: string with concatenated relevant content

// Expand context around a specific chunk
const expandedChunks = await agent.expandKnowledgeContext(
  documentId,   // Document ID (UUID string)
  chunkIndex,   // Chunk index within document
  2,            // expandBefore: chunks to include before (default: 1)
  2             // expandAfter: chunks to include after (default: 1)
);
// Returns: Array<string> with expanded chunk content

配置

环境变量

# Database (required)
KNOWLEDGE_DB_URL=postgresql://user:password@host:port/database

# API key for embeddings
OPENAI_API_KEY=your_openai_key
# Or use dedicated embedding keys:
OPENAI_EMBEDDING_API_KEY=your_embedding_key
OPENAI_EMBEDDING_BASE_URL=https://api.openai.com/v1  # Optional: custom endpoint for embeddings
GEMINI_API_KEY=your_gemini_key
GEMINI_EMBEDDING_API_KEY=your_gemini_embedding_key

# For Ollama embeddings (local)
OLLAMA_BASE_URL=http://localhost:11434

嵌入模型配置

直接在代理配置中指定嵌入模型:

const agent = await Agent.create({
  name: 'KnowledgeAgent',
  model: 'gpt-4o',
  embeddingModel: 'text-embedding-3-small',  // Specify embedding model here
  knowledge: true
});

响应类型

了解知识库方法的响应,有助于你更高效地处理数据。

添加知识响应

添加知识会返回所创建文档的 UUID:

const documentId = await agent.addKnowledge(
  "TypeScript is a typed superset of JavaScript...",
  "TypeScript Overview",
  { source: "documentation", version: "5.0" }
);

// Response: "550e8400-e29b-41d4-a716-446655440000" (UUID string)

搜索知识响应

搜索会返回一个包含内容、元数据和相似度分数的块数组:

const results = await agent.searchKnowledge("TypeScript types", 5, 0.7);

// Response structure:
[
  {
    content: "TypeScript provides static typing which helps catch errors at compile time...",
    metadata: {
      title: "TypeScript Overview",
      source: "documentation",
      version: "5.0"
    },
    similarity: 0.95
  },
  {
    content: "Types in TypeScript include primitives like string, number, boolean...",
    metadata: {
      title: "Type System",
      source: "tutorial"
    },
    similarity: 0.87
  },
  {
    content: "Advanced types like generics and conditional types provide powerful abstractions...",
    metadata: {
      title: "Advanced Types",
      source: "documentation"
    },
    similarity: 0.79
  }
]

获取知识上下文响应

上下文检索会返回一个由相关块拼接而成的字符串:

const context = await agent.getKnowledgeContext("TypeScript", 3);

// Response: concatenated string with separator
"TypeScript is a typed superset of JavaScript...\n\n---\n\nTypes help catch errors at compile time...\n\n---\n\nAdvanced types provide powerful abstractions..."

获取知识文档响应

列出文档会返回所有已存储文档的元数据:

const documents = await agent.getKnowledgeDocuments();

// Response structure:
[
  {
    id: "doc-uuid-1",                      // UUID string
    title: "TypeScript Overview",
    created_at: "2024-01-15T10:30:00Z"    // ISO 8601 timestamp
  },
  {
    id: "doc-uuid-2",
    title: "Advanced Types",
    created_at: "2024-01-16T14:20:00Z"
  },
  {
    id: "doc-uuid-3",
    title: "Best Practices",
    created_at: "2024-01-17T09:15:00Z"
  }
]

扩展知识上下文响应

上下文扩展会返回一个包含文本块字符串的数组:

const chunks = await agent.expandKnowledgeContext("doc-uuid", 5, 2, 2);

// Response structure (plain chunk content):
[
  "Earlier context before the target chunk...",
  "More context leading to the target...",
  "This is the target chunk with the main content...",
  "Following context after the target...",
  "Additional context for full understanding..."
]

删除响应

删除操作会返回布尔值,指示是否成功:

// Delete specific document
const docDeleted = await agent.deleteKnowledgeDocument("doc-uuid");
// Returns: true or false

// Delete specific chunk
const chunkDeleted = await agent.deleteKnowledgeChunk("chunk-uuid");
// Returns: true or false

清除知识库响应

清除所有知识不会返回值(void):

await agent.clearKnowledge();
// Returns: void (undefined)

文件操作响应

基于文件的知识操作在成功时不返回值,失败时抛出异常:

// Add from file
await agent.addKnowledgeFromFile('./document.pdf', { source: 'manual' });
// Returns: void

// Add from directory
await agent.addKnowledgeFromDirectory('./docs', { project: 'main' });
// Returns: void

最后更新时间:2026年7月6日

本节内容

简介

在 Astreus 文档中了解简介，获取用于构建智能体系统的设置指导、API 模式和实用示例。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

安装

使用 npm、yarn 或 pnpm 安装 Astreus,确认所需的 Node.js 版本,并准备好本地项目以使用该框架构建 AI 代理。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

快速开始

在 Astreus 文档中了解快速开始，获取用于构建智能体系统的设置指导、API 模式和实用示例。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

智能体

在 Astreus 文档中了解智能体，获取用于构建智能体系统的设置指导、API 模式和实用示例。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

调度器

LLM