ナレッジ

Astreusのドキュメントでナレッジについて学び、エージェントシステムを構築するためのセットアップの手引き、APIのパターン、実践的な例を確認しましょう。信頼性の高いAstreusエージェントシステムを構築するために必要なセットアップのパターン、API、実践的な例を学びましょう。

ドキュメント処理とベクトル検索を伴うRAG統合

概要

ナレッジシステムは、検索拡張生成（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)

ファイル操作のレスポンス

ファイルベースのナレッジ操作は、成功時にvoidを返し、エラー時には例外をスローします。

// 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日

このセクション内

はじめに

実世界のタスクを効果的に解決する自律システムを構築するための、オープンソースAIエージェントフレームワーク。信頼性の高いAstreusエージェントシステムを構築するために必要なセットアップのパターン、API、実践的な例を学びましょう。

インストール

npm、yarn、pnpmでAstreusをインストールし、必要なNode.jsのバージョンを確認して、フレームワークでAIエージェントを構築するためのローカルプロジェクトを準備します。

クイックスタート

Astreusのドキュメントでクイックスタートについて学び、エージェントシステムを構築するためのセットアップの手引き、APIのパターン、実践的な例を確認しましょう。信頼性の高いAstreusエージェントシステムを構築するために必要なセットアップのパターン、API、実践的な例を学びましょう。

エージェント

Astreusのドキュメントでエージェントについて学び、エージェントシステムを構築するためのセットアップの手引き、APIのパターン、実践的な例を確認しましょう。信頼性の高いAstreusエージェントシステムを構築するために必要なセットアップのパターン、API、実践的な例を学びましょう。

スケジューラー

LLM