AgentDB向量搜索 - 高性能语义搜索工具，比传统方案快150-12500倍

AgentDB Vector Search by ruvnet/claude-flow

27,500 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/ruvnet/claude-flow --skill 'AgentDB Vector Search'

AI/机器学习 Node.js 数据库

🇨🇳中文介绍

AgentDB 向量搜索

功能概述

利用 AgentDB 的高性能向量数据库实现基于向量的语义搜索，其操作速度比传统解决方案快 150 倍至 12,500 倍。具备 HNSW 索引、量化和亚毫秒级搜索（<100µs）功能。

先决条件

Node.js 18+
AgentDB v1.0.7+（通过 agentic-flow 或独立安装）
OpenAI API 密钥（用于嵌入）或自定义嵌入模型

使用 CLI 快速开始

初始化向量数据库

# 使用默认维度初始化（OpenAI ada-002 为 1536）
npx agentdb@latest init .$vectors.db

# 为不同的嵌入模型自定义维度
npx agentdb@latest init .$vectors.db --dimension 768  # sentence-transformers
npx agentdb@latest init .$vectors.db --dimension 384  # all-MiniLM-L6-v2

# 使用预设配置
npx agentdb@latest init .$vectors.db --preset small   # <10K 向量
npx agentdb@latest init .$vectors.db --preset medium  # 10K-100K 向量
npx agentdb@latest init .$vectors.db --preset large   # >100K 向量

# 用于测试的内存数据库
npx agentdb@latest init .$vectors.db --in-memory

查询向量数据库

# 基本相似性搜索
npx agentdb@latest query .$vectors.db "[0.1,0.2,0.3,...]"

# 返回 Top-k 结果
npx agentdb@latest query .$vectors.db "[0.1,0.2,0.3]" -k 10

# 带相似度阈值（余弦相似度）
npx agentdb@latest query .$vectors.db "0.1 0.2 0.3" -t 0.75 -m cosine

# 不同的距离度量
npx agentdb@latest query .$vectors.db "[...]" -m euclidean  # L2 距离
npx agentdb@latest query .$vectors.db "[...]" -m dot        # 点积

# 用于自动化的 JSON 输出
npx agentdb@latest query .$vectors.db "[...]" -f json -k 5

# 包含距离的详细输出
npx agentdb@latest query .$vectors.db "[...]" -v

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

使用 API 快速开始

import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow$reasoningbank';

// 使用向量搜索优化进行初始化
const adapter = await createAgentDBAdapter({
  dbPath: '.agentdb$vectors.db',
  enableLearning: false,       // 仅向量搜索
  enableReasoning: true,       // 启用语义匹配
  quantizationType: 'binary',  // 内存减少 32 倍
  cacheSize: 1000,             // 快速检索
});

// 存储带有嵌入的文档
const text = "The quantum computer achieved 100 qubits";
const embedding = await computeEmbedding(text);

await adapter.insertPattern({
  id: '',
  type: 'document',
  domain: 'technology',
  pattern_data: JSON.stringify({
    embedding,
    text,
    metadata: { category: "quantum", date: "2025-01-15" }
  }),
  confidence: 1.0,
  usage_count: 0,
  success_count: 0,
  created_at: Date.now(),
  last_used: Date.now(),
});

// 使用 MMR（最大边际相关性）进行语义搜索
const queryEmbedding = await computeEmbedding("quantum computing advances");
const results = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'technology',
  k: 10,
  useMMR: true,              // 多样化结果
  synthesizeContext: true,    // 丰富的上下文
});

// 自动嵌入存储
await db.storeWithEmbedding({
  content: "Your document text",
  metadata: { source: "docs", page: 42 }
});

// 查找相似文档
const similar = await db.findSimilar("quantum computing", {
  limit: 5,
  minScore: 0.75
});

3. 混合搜索（向量 + 元数据）

// 结合向量相似度和元数据过滤
const results = await db.hybridSearch({
  query: "machine learning models",
  filters: {
    category: "research",
    date: { $gte: "2024-01-01" }
  },
  limit: 20
});

RAG（检索增强生成）

// 构建 RAG 管道
async function ragQuery(question: string) {
  // 1. 获取相关上下文
  const context = await db.searchSimilar(
    await embed(question),
    { limit: 5, threshold: 0.7 }
  );

  // 2. 结合上下文生成答案
  const prompt = `Context: ${context.map(c => c.text).join('\n')}
Question: ${question}`;

  return await llm.generate(prompt);
}

// 高效的批量存储
await db.batchStore(documents.map(doc => ({
  text: doc.content,
  embedding: doc.vector,
  metadata: doc.meta
})));

# 为 Claude Code 启动 AgentDB MCP 服务器
npx agentdb@latest mcp

# 添加到 Claude Code（一次性设置）
claude mcp add agentdb npx agentdb@latest mcp

# 现在可以在 Claude Code 中使用 MCP 工具：
# - agentdb_query: 语义向量搜索
# - agentdb_store: 存储带有嵌入的文档
# - agentdb_stats: 数据库统计信息

# 运行全面的基准测试
npx agentdb@latest benchmark

# 结果：
# ✅ 模式搜索：快 150 倍（100µs 对比 15ms）
# ✅ 批量插入：快 500 倍（100 个向量 2ms 对比 1s）
# ✅ 大规模查询：快 12,500 倍（1M 向量 8ms 对比 100s）
# ✅ 内存效率：通过量化减少 4-32 倍

AgentDB 提供多种量化策略以提高内存效率：

二进制量化（减少 32 倍）

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',  // 768 维 → 96 字节
});

标量量化（减少 4 倍）

const adapter = await createAgentDBAdapter({
  quantizationType: 'scalar',  // 768 维 → 768 字节
});

乘积量化（减少 8-16 倍）

const adapter = await createAgentDBAdapter({
  quantizationType: 'product',  // 768 维 → 48-96 字节
});

# 余弦相似度（默认，适用于大多数用例）
npx agentdb@latest query .$db.sqlite "[...]" -m cosine

# 欧几里得距离（L2 范数）
npx agentdb@latest query .$db.sqlite "[...]" -m euclidean

# 点积（用于归一化向量）
npx agentdb@latest query .$db.sqlite "[...]" -m dot

O(log n) 搜索复杂度
亚毫秒级检索 (<100µs)
自动索引构建

1000 个模式的内存缓存
< 1ms 模式检索
自动缓存失效

MMR（最大边际相关性）

多样化的结果集
避免冗余
平衡相关性和多样性

启用 HNSW 索引：AgentDB 自动启用，速度快 10-100 倍
使用量化：二进制（减少 32 倍）、标量（减少 4 倍）、乘积（减少 8-16 倍）内存占用
批量操作：批量插入速度快 500 倍
匹配维度：1536（OpenAI）、768（sentence-transformers）、384（MiniLM）
相似度阈值：从 0.7 开始以保证质量，根据用例调整
启用缓存：为频繁查询提供 1000 个模式的缓存

问题：搜索性能慢

# 检查 HNSW 索引是否启用（自动）
npx agentdb@latest stats .$vectors.db

# 期望值：搜索时间 <100µs

问题：内存使用率高

# 启用二进制量化（减少 32 倍）
# 在适配器中使用：quantizationType: 'binary'

问题：相关性差

# 调整相似度阈值
npx agentdb@latest query .$db.sqlite "[...]" -t 0.8  # 更高阈值

# 或使用 MMR 以获得多样化结果
# 在适配器中使用：useMMR: true

问题：维度错误

# 检查嵌入模型维度：
# - OpenAI ada-002: 1536
# - sentence-transformers: 768
# - all-MiniLM-L6-v2: 384

npx agentdb@latest init .$db.sqlite --dimension 768

数据库统计信息

# 获取全面的统计信息
npx agentdb@latest stats .$vectors.db

# 显示：
# - 总模式/向量数
# - 数据库大小
# - 平均置信度
# - 领域分布
# - 索引状态

向量搜索：<100µs（HNSW 索引）
模式检索：<1ms（带缓存）
批量插入：100 个向量 2ms
内存效率：通过量化减少 4-32 倍
可扩展性：高效处理 1M+ 向量
延迟：大多数操作为亚毫秒级

GitHub：https:/$github.com$ruvnet$agentic-flow$tree$main$packages$agentdb
文档：node_modules$agentic-flow/docs/AGENTDB_INTEGRATION.md
MCP 集成：npx agentdb@latest mcp 用于 Claude Code
网站：https:/$agentdb.ruv.io
CLI 帮助：npx agentdb@latest --help
命令帮助：npx agentdb@latest help <command>

🇺🇸English

AgentDB Vector Search

What This Skill Does

Implements vector-based semantic search using AgentDB's high-performance vector database with 150x-12,500x faster operations than traditional solutions. Features HNSW indexing, quantization, and sub-millisecond search (<100µs).

Prerequisites

Node.js 18+
AgentDB v1.0.7+ (via agentic-flow or standalone)
OpenAI API key (for embeddings) or custom embedding model

Quick Start with CLI

Initialize Vector Database

# Initialize with default dimensions (1536 for OpenAI ada-002)
npx agentdb@latest init .$vectors.db

# Custom dimensions for different embedding models
npx agentdb@latest init .$vectors.db --dimension 768  # sentence-transformers
npx agentdb@latest init .$vectors.db --dimension 384  # all-MiniLM-L6-v2

# Use preset configurations
npx agentdb@latest init .$vectors.db --preset small   # <10K vectors
npx agentdb@latest init .$vectors.db --preset medium  # 10K-100K vectors
npx agentdb@latest init .$vectors.db --preset large   # >100K vectors

# In-memory database for testing
npx agentdb@latest init .$vectors.db --in-memory

Query Vector Database

# Basic similarity search
npx agentdb@latest query .$vectors.db "[0.1,0.2,0.3,...]"

# Top-k results
npx agentdb@latest query .$vectors.db "[0.1,0.2,0.3]" -k 10

# With similarity threshold (cosine similarity)
npx agentdb@latest query .$vectors.db "0.1 0.2 0.3" -t 0.75 -m cosine

# Different distance metrics
npx agentdb@latest query .$vectors.db "[...]" -m euclidean  # L2 distance
npx agentdb@latest query .$vectors.db "[...]" -m dot        # Dot product

# JSON output for automation
npx agentdb@latest query .$vectors.db "[...]" -f json -k 5

# Verbose output with distances
npx agentdb@latest query .$vectors.db "[...]" -v

Import/Export Vectors

# Export vectors to JSON
npx agentdb@latest export .$vectors.db .$backup.json

# Import vectors from JSON
npx agentdb@latest import .$backup.json

# Get database statistics
npx agentdb@latest stats .$vectors.db

Quick Start with API

import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow$reasoningbank';

// Initialize with vector search optimizations
const adapter = await createAgentDBAdapter({
  dbPath: '.agentdb$vectors.db',
  enableLearning: false,       // Vector search only
  enableReasoning: true,       // Enable semantic matching
  quantizationType: 'binary',  // 32x memory reduction
  cacheSize: 1000,             // Fast retrieval
});

// Store document with embedding
const text = "The quantum computer achieved 100 qubits";
const embedding = await computeEmbedding(text);

await adapter.insertPattern({
  id: '',
  type: 'document',
  domain: 'technology',
  pattern_data: JSON.stringify({
    embedding,
    text,
    metadata: { category: "quantum", date: "2025-01-15" }
  }),
  confidence: 1.0,
  usage_count: 0,
  success_count: 0,
  created_at: Date.now(),
  last_used: Date.now(),
});

// Semantic search with MMR (Maximal Marginal Relevance)
const queryEmbedding = await computeEmbedding("quantum computing advances");
const results = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'technology',
  k: 10,
  useMMR: true,              // Diverse results
  synthesizeContext: true,    // Rich context
});

Core Features

1. Vector Storage

// Store with automatic embedding
await db.storeWithEmbedding({
  content: "Your document text",
  metadata: { source: "docs", page: 42 }
});

2. Similarity Search

// Find similar documents
const similar = await db.findSimilar("quantum computing", {
  limit: 5,
  minScore: 0.75
});

3. Hybrid Search (Vector + Metadata)

// Combine vector similarity with metadata filtering
const results = await db.hybridSearch({
  query: "machine learning models",
  filters: {
    category: "research",
    date: { $gte: "2024-01-01" }
  },
  limit: 20
});

Advanced Usage

RAG (Retrieval Augmented Generation)

// Build RAG pipeline
async function ragQuery(question: string) {
  // 1. Get relevant context
  const context = await db.searchSimilar(
    await embed(question),
    { limit: 5, threshold: 0.7 }
  );

  // 2. Generate answer with context
  const prompt = `Context: ${context.map(c => c.text).join('\n')}
Question: ${question}`;

  return await llm.generate(prompt);
}

Batch Operations

// Efficient batch storage
await db.batchStore(documents.map(doc => ({
  text: doc.content,
  embedding: doc.vector,
  metadata: doc.meta
})));

MCP Server Integration

# Start AgentDB MCP server for Claude Code
npx agentdb@latest mcp

# Add to Claude Code (one-time setup)
claude mcp add agentdb npx agentdb@latest mcp

# Now use MCP tools in Claude Code:
# - agentdb_query: Semantic vector search
# - agentdb_store: Store documents with embeddings
# - agentdb_stats: Database statistics

Performance Benchmarks

# Run comprehensive benchmarks
npx agentdb@latest benchmark

# Results:
# ✅ Pattern Search: 150x faster (100µs vs 15ms)
# ✅ Batch Insert: 500x faster (2ms vs 1s for 100 vectors)
# ✅ Large-scale Query: 12,500x faster (8ms vs 100s at 1M vectors)
# ✅ Memory Efficiency: 4-32x reduction with quantization

Quantization Options

AgentDB provides multiple quantization strategies for memory efficiency:

Binary Quantization (32x reduction)

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',  // 768-dim → 96 bytes
});

Scalar Quantization (4x reduction)

const adapter = await createAgentDBAdapter({
  quantizationType: 'scalar',  // 768-dim → 768 bytes
});

Product Quantization (8-16x reduction)

const adapter = await createAgentDBAdapter({
  quantizationType: 'product',  // 768-dim → 48-96 bytes
});

Distance Metrics

# Cosine similarity (default, best for most use cases)
npx agentdb@latest query .$db.sqlite "[...]" -m cosine

# Euclidean distance (L2 norm)
npx agentdb@latest query .$db.sqlite "[...]" -m euclidean

# Dot product (for normalized vectors)
npx agentdb@latest query .$db.sqlite "[...]" -m dot

Advanced Features

HNSW Indexing

O(log n) search complexity
Sub-millisecond retrieval (<100µs)
Automatic index building

Caching

1000 pattern in-memory cache
< 1ms pattern retrieval
Automatic cache invalidation

MMR (Maximal Marginal Relevance)

Diverse result sets
Avoid redundancy
Balance relevance and diversity

Performance Tips

Enable HNSW indexing : Automatic with AgentDB, 10-100x faster
Use quantization : Binary (32x), Scalar (4x), Product (8-16x) memory reduction
Batch operations : 500x faster for bulk inserts
Match dimensions : 1536 (OpenAI), 768 (sentence-transformers), 384 (MiniLM)
Similarity threshold : Start at 0.7 for quality, adjust based on use case
Enable caching : 1000 pattern cache for frequent queries

Troubleshooting

Issue: Slow search performance

# Check if HNSW indexing is enabled (automatic)
npx agentdb@latest stats .$vectors.db

# Expected: <100µs search time

Issue: High memory usage

# Enable binary quantization (32x reduction)
# Use in adapter: quantizationType: 'binary'

Issue: Poor relevance

# Adjust similarity threshold
npx agentdb@latest query .$db.sqlite "[...]" -t 0.8  # Higher threshold

# Or use MMR for diverse results
# Use in adapter: useMMR: true

Issue: Wrong dimensions

# Check embedding model dimensions:
# - OpenAI ada-002: 1536
# - sentence-transformers: 768
# - all-MiniLM-L6-v2: 384

npx agentdb@latest init .$db.sqlite --dimension 768

Database Statistics

# Get comprehensive stats
npx agentdb@latest stats .$vectors.db

# Shows:
# - Total patterns$vectors
# - Database size
# - Average confidence
# - Domains distribution
# - Index status

Performance Characteristics

Vector Search : <100µs (HNSW indexing)
Pattern Retrieval : <1ms (with cache)
Batch Insert : 2ms for 100 vectors
Memory Efficiency : 4-32x reduction with quantization
Scalability : Handles 1M+ vectors efficiently
Latency : Sub-millisecond for most operations

Learn More

GitHub: https:/$github.com$ruvnet$agentic-flow$tree$main$packages$agentdb
Documentation: node_modules$agentic-flow/docs/AGENTDB_INTEGRATION.md
MCP Integration: npx agentdb@latest mcp for Claude Code
Website: https:/$agentdb.ruv.io
CLI Help: npx agentdb@latest --help
Command Help: npx agentdb@latest help <command>

Weekly Installs

–

Repository

ruvnet/claude-flow

GitHub Stars

27.5K

First Seen

–

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

超能力技能使用指南：AI助手技能调用优先级与工作流程详解

43,500 周安装