- name
- pinecone-search
- description
- Pinecone vector search and document upload tool for knowledge base management
- tags
- keywords
- version
- 1.1.0
- author
- deki18
- license
- MIT
- homepage
- https://github.com/deki18/pinecone-search
- repository
- https://github.com/deki18/pinecone-search
- type
- skill
- environment_variables
- required
- optional
Pinecone Search
Pinecone 向量搜索与文档上传工具，支持 TXT、Markdown 格式文件的上传、分块、向量嵌入和搜索。
功能特性
- 📤 文档上传: 支持 TXT、Markdown 文件上传
- 🧩 智能分块: 递归字符分割，保持语义完整
- 🔢 向量嵌入: OpenAI 兼容 API，批量嵌入
- 🔍 向量搜索: 基于 Pinecone 的相似度搜索
- 📊 上传统计: 详细的文件和块级别统计信息
- 🏷️ 命名空间: 支持多项目隔离
安装
pip install -r requirements.txt
cp config.example.env .env
# 编辑 .env 文件，填入你的 API Key配置
编辑 .env 文件：
PINECONE_API_KEY=your_pinecone_api_key
EMBEDDING_API_KEY=your_embedding_api_key
EMBEDDING_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-large
INDEX_NAME=your-index-name
NAMESPACE=（可选，默认为default）使用
上传文档
# 上传单个文件
python upload.py path/to/file.txt
# 上传多个文件
python upload.py file1.txt file2.md
# 上传整个目录
python upload.py ./docs/ --recursive
# 指定命名空间
python upload.py ./docs/ --namespace project-a
# 自定义分块大小
python upload.py ./docs/ --chunk-size 512 --overlap 100
# 预览模式（不实际上传）
python upload.py ./docs/ --dry-run
# JSON 格式输出（供 agent 使用）
python upload.py ./docs/ --json搜索知识库
# 基础搜索
python search.py "查询内容"
# 返回更多结果
python search.py "查询内容" --top-k 10
# 按命名空间过滤
python search.py "查询" --namespace project-a
# 按文件类型过滤
python search.py "查询" --file-type markdown
# 按文件名过滤
python search.py "查询" --filename "施工规范"
# 设置相似度阈值
python search.py "查询" --min-score 0.7
# 纯向量搜索（禁用混合搜索）
python search.py "查询" --no-hybrid
# 显示详细分数
python search.py "查询" --verbose
# 组合使用
python search.py "混凝土标准" --file-type markdown --min-score 0.6 --top-k 5触发关键词
- 规范、标准
- 查询资料、知识库
- 上传文档、添加文件、pineone
示例
上传示例
python upload.py "施工规范.md" --namespace construction输出：
📤 正在上传文件: 施工规范.md
============================================================
📊 上传统计报告
============================================================
🏢 Workspace: workspace
📁 Namespace: construction
📄 总文件数: 1
🧩 总块数: 15
✅ 成功上传: 15
❌ 失败: 0
⏱️ 耗时: 3.25 秒
⚡ 平均速度: 4.62 chunks/秒
📋 文件详情:
------------------------------------------------------------
📄 施工规范.md
路径: D:\docs\施工规范.md
类型: markdown
块数: 15
Token数: 12580
成功: 15
============================================================搜索示例
python search.py "混凝土浇筑标准是什么？"输出：
🔍 正在搜索: 混凝土浇筑标准是什么？
📋 过滤条件: 混合搜索(候选集=20)
======================================================================
【结果 #1】
匹配度: 0.8934
来源: D:\docs\施工规范.md
文件名: 施工规范.md
标题: 混凝土施工规范
文件类型: markdown
块索引: 1/15
内容:
混凝土浇筑应符合以下标准：
1. 浇筑前应检查模板和钢筋
2. 混凝土应连续浇筑，避免冷缝
...
----------------------------------------------------------------------详细分数示例（使用 --verbose）
python search.py "混凝土标准" --verbose --min-score 0.6输出：
🔍 正在搜索: 混凝土标准
📋 过滤条件: 相似度≥0.6 | 混合搜索(候选集=20)
======================================================================
【结果 #1】
🏆 混合分数: 0.8234
📊 向量分数: 0.8012
📝 BM25分数: 0.8756
来源: D:\docs\施工规范.md
...技术细节
文本分割策略
参考 LangChain RecursiveCharacterTextSplitter：
- 优先按段落分割 (`\
\ `)
- 其次按句子分割 (`\
、。、. `)
- 最后按字符分割
向量嵌入
- 支持 OpenAI text-embedding-3-large/small
- 批量嵌入：30 条/批次
- 指数退避重试机制
Pinecone 上传
- 自适应批次大小（2MB 限制自动减半）
- 元数据包含：文件名、路径、块索引、token 数量
- 支持命名空间隔离
混合搜索（向量 + 关键词 BM25）
搜索流程：
- 向量召回：从 Pinecone 召回 20 个最相似的候选结果
- 关键词匹配：使用简化版 BM25 算法计算关键词匹配分数
- 混合排序：综合向量分数（70%）和 BM25 分数（30%）重新排序
- 返回 Top-K：返回最终排序后的前 K 个结果
混合搜索优势：
- 结合语义理解（向量）和精确匹配（关键词）
- 提高长尾查询的准确性
- 对专业术语和特定词汇更敏感
返回给 Agent 的 JSON 格式
{
"workspace": "workspace",
"namespace": "construction",
"total_files": 1,
"total_chunks": 15,
"successful_chunks": 15,
"failed_chunks": 0,
"duration_seconds": 3.25,
"files": [
{
"filename": "施工规范.md",
"source": "D:\\docs\\施工规范.md",
"file_type": "markdown",
"chunks": 15,
"successful": 15,
"failed": 0,
"tokens": 12580
}
]
}