名称： voyageai
描述： >
Voyage AI 嵌入与重排序 CLI，与 MongoDB Atlas Vector Search 集成。
用途：生成文本嵌入、重排序搜索结果、在 Atlas 中存储嵌入、执行向量相似性搜索、创建向量搜索索引、列出可用模型、比较文本相似性、批量导入、交互式演示以及学习 AI 概念。
触发词：嵌入文本、生成嵌入、向量搜索、重排序文档、voyage ai、语义搜索、相似性搜索、存储嵌入、atlas 向量搜索、嵌入模型、余弦相似性、批量导入、解释嵌入。
元数据：
openclaw:
emoji: "🧭"
author:
name: Michael Lynn
url: https://mlynn.org
github: mrlynn
version: "1.4.0"
license: MIT
tags:
- 嵌入
- 向量搜索
- 重排序
- mongodb
- atlas
- 语义搜索
- rag
- voyage-ai
requires:
bins:
- vai
env:
- VOYAGE_API_KEY
install:
- id: npm
kind: npm
package: voyageai-cli
global: true

🧭 Voyage AI 技能

使用 vai CLI (voyageai-cli) 进行 Voyage AI 嵌入、重排序和 MongoDB Atlas 向量搜索。纯 Node.js 实现，无需 Python。

设置

npm install -g voyageai-cli

环境变量

获取 API 密钥：MongoDB Atlas → AI Models → Create model API key

命令参考 (14 个命令)

embed — 生成嵌入向量

vai embed "什么是 MongoDB?"
vai embed "搜索查询" --model voyage-4-large --input-type query --dimensions 512
vai embed --file document.txt --input-type document
cat texts.txt | vai embed
vai embed "hello" --output-format array

rerank — 重排序文档

vai rerank --query "数据库性能" --documents "MongoDB 很快" "SQL 是关系型的"
vai rerank --query "最佳数据库" --documents-file candidates.json --top-k 3

store — 嵌入并存储到 Atlas

vai store --db mydb --collection docs --field embedding \
  --text "MongoDB Atlas 是一个云数据库" \
  --metadata '{"source": "docs"}'

# 从 JSONL 批量处理
vai store --db mydb --collection docs --field embedding --file documents.jsonl

search — 向量搜索

vai search --query "云数据库" --db mydb --collection docs \
  --index vector_index --field embedding

# 带预过滤
vai search --query "性能" --db mydb --collection docs \
  --index vector_index --field embedding --filter '{"category": "guides"}' --limit 5

index — 管理向量搜索索引

vai index create --db mydb --collection docs --field embedding \
  --dimensions 1024 --similarity cosine --index-name my_index
vai index list --db mydb --collection docs
vai index delete --db mydb --collection docs --index-name my_index

models — 列出可用模型

vai models
vai models --type embedding
vai models --type reranking
vai models --json

ping — 测试连接性

vai ping
vai ping --json

config — 管理持久化配置

vai config set api-key "pa-your-key"
echo "pa-your-key" | vai config set api-key --stdin
vai config get
vai config delete api-key
vai config path
vai config reset

demo — 交互式引导演示

vai demo
vai demo --no-pause
vai demo --skip-pipeline
vai demo --keep

explain — 学习 AI 概念

vai explain                      # 列出所有主题
vai explain embeddings
vai explain reranking
vai explain vector-search
vai explain rag
vai explain cosine-similarity
vai explain two-stage-retrieval
vai explain input-type
vai explain models
vai explain api-keys
vai explain api-access
vai explain batch-processing

similarity — 比较文本相似性

vai similarity "MongoDB 是一个文档数据库" "MongoDB Atlas 是一个云数据库"
vai similarity "数据库性能" --against "MongoDB 很快" "PostgreSQL 是关系型的"
vai similarity --file1 doc1.txt --file2 doc2.txt
vai similarity "文本 A" "文本 B" --json

ingest — 带进度显示的批量导入

vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding
vai ingest --file data.csv --db myapp --collection docs --field embedding --text-column content
vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding \
  --model voyage-4 --batch-size 100 --input-type document
vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding --dry-run

completions — Shell 自动补全脚本

vai completions bash    # 输出 bash 自动补全脚本
vai completions zsh     # 输出 zsh 自动补全脚本

# 安装 bash 自动补全
vai completions bash >> ~/.bashrc && source ~/.bashrc

# 安装 zsh 自动补全
vai completions zsh > ~/.zsh/completions/_vai

help — 显示帮助

vai help
vai help embed
vai embed --help

常见工作流

嵌入 → 存储 → 搜索流程

# 1. 存储文档
vai store --db myapp --collection articles --field embedding \
  --text "MongoDB Atlas 提供完全托管的云数据库服务" \
  --metadata '{"title": "Atlas 概述"}'

# 2. 创建索引
vai index create --db myapp --collection articles --field embedding \
  --dimensions 1024 --similarity cosine --index-name article_search

# 3. 搜索
vai search --query "云数据库如何工作" \
  --db myapp --collection articles --index article_search --field embedding

两阶段检索 (嵌入 + 重排序)

# 1. 通过向量搜索获取候选文档
vai search --query "数据库扩展" --db myapp --collection articles \
  --index article_search --field embedding --limit 20 --json > candidates.json

# 2. 重排序以提高精度
vai rerank --query "数据库扩展" --documents-file candidates.json --top-k 5

批量导入流程

# 1. 验证数据 (试运行)
vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding --dry-run

# 2. 带进度显示的导入
vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding

# 3. 创建索引
vai index create --db myapp --collection docs --field embedding \
  --dimensions 1024 --similarity cosine

全局标志

参考

• 模型目录 — 包含定价和规格的所有模型
• 向量搜索模式 — Atlas 向量搜索集成指南