PinRAG

PinRAG

概述

PinRAG 适用于你想了解某个主题，但资料散落各处的情况——PDF 和电子书、GitHub 仓库、YouTube 视频、Discord 讨论，以及纯文本笔记。你可以将这些资料编入一个共享的 RAG 索引，然后通过 Cursor、VS Code（GitHub Copilot）或任何支持 MCP 的助手提问，并获得附有引用的答案，引用会指向相应的页面、时间戳、文件或讨论串。

其底层是使用 LangChain 构建的检索增强生成，并以 MCP（Model Context Protocol）服务的形式提供：你可以在编辑器中添加文档，使用自然语言查询，并列出或移除已编入索引的内容。支持的输入包括 PDF、本地文本文件和目录、Discord 导出内容、YouTube（通过 URL、播放列表或 ID 获取字幕），以及 GitHub 仓库 URL。对于 YouTube，你还可以选择添加视觉信息，将屏幕上的代码、图表和界面文本与字幕合并到相同的文本块中——请参阅YouTube 视觉增强。

功能

• 多格式索引 — PDF（.pdf）、本地文件或目录、纯文本（.txt）、Discord 导出文件（.txt）、YouTube（视频或播放列表 URL，或视频 ID）、GitHub 仓库（URL）、网页文档站点（URL）
• 可选的 YouTube 视觉分析 — 默认关闭。启用后，会运行视觉模型（OpenAI、Anthropic 或 OpenRouter 原生视频），并将结构化的屏幕内容上下文与转录内容合并，使 RAG 分块包含可搜索的代码名称、标签和图表，而不只有语音内容。OpenRouter 模式无需本地 ffmpeg 或视频下载；openai/anthropic 使用场景关键帧，并需要 pinrag[vision] + ffmpeg（参见YouTube 视觉增强）
• 带引用的 RAG — 答案会引用来源上下文：PDF 页码、YouTube 时间戳、纯文本和 Discord 的文档名称、GitHub 仓库的分块索引、网页文档的来源 URL
• 文档标签 — 在索引时为文档添加标签（例如 AMIGA、PI_PICO），以便筛选搜索结果
• 元数据筛选 — query_tool 支持 document_id、tag、document_type、PDF 的 page_min/page_max，以及 response_style（详细或简洁）
• MCP 工具 — add_document_tool、query_tool、list_documents_tool、remove_document_tool、set_document_tag_tool、list_collections_tool；工具上的可选 collection 会在本次调用中覆盖 PINRAG_COLLECTION_NAME
• MCP 资源 — pinrag://documents（已索引的文档）和 pinrag://server-config（环境变量和配置）；点击 Cursor 的 MCP 面板即可查看
• MCP 提示词 — use_pinrag（参数：request），用于查询、索引、列出或移除文档
• 可配置的 LLM — OpenRouter（默认，免费 openrouter/free 路由器）、OpenAI、Anthropic 或 Cerebras Inference（兼容 OpenAI 的 API）；可在 MCP env 或 shell 中通过 PINRAG_LLM_PROVIDER 和 PINRAG_LLM_MODEL 设置
• 本地嵌入 — Nomic（PINRAG_EMBEDDING_MODEL，默认值为 nomic-embed-text-v1.5）；无需 API 密钥；首次运行时会下载模型权重（约 270 MB，并会缓存）
• 检索与分块选项 — 默认启用结构感知分块；可选 FlashRank 重排序、多查询扩展，以及适用于 PDF 的父子分块（参见配置）
• 可观测性 — MCP 工具通知（ctx.log），以及可选的 LangSmith 跟踪
• 基于 — LangChain、Chroma；可选 OpenRouter、OpenAI、Anthropic、FlashRank

安装

在编辑器中将 PinRAG 添加为 MCP 服务。安装 uv，并确保 uvx 位于 PATH 中——它会从 PyPI 运行 PinRAG，无需预先执行 pip install。

Cursor： 将以下内容添加到 ~/.cursor/mcp.json 的 mcpServers 下：

{
  "mcpServers": {
    "pinrag": {
      "command": "uvx",
      "args": ["--refresh", "pinrag"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key-here",
        "PINRAG_PERSIST_DIR": "/absolute/path/to/your/pinrag-data"
      }
    }
  }
}

VS Code（GitHub Copilot）： 从命令面板运行 MCP: Open User Configuration（或在工作区中添加 .vscode/mcp.json），然后合并以下结构——顶层键为 servers：

{
  "servers": {
    "pinrag": {
      "command": "uvx",
      "args": ["--refresh", "pinrag"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key-here",
        "PINRAG_PERSIST_DIR": "/absolute/path/to/your/pinrag-data"
      }
    }
  }
}

快速开始

HTTP 服务模式

对于通过 HTTP 使用 MCP 的客户端（例如使用 --server 的 pinrag-cli），运行：

pinrag server [--host 127.0.0.1] [--port 8765]

这会在 http://<host>:<port>/mcp 启动一个可流式传输的 HTTP MCP 端点。编辑器使用的默认 pinrag stdio 命令保持不变；pinrag server 是新增命令。使用 --server http://127.0.0.1:8765/mcp 连接 pinrag-cli。

配置 MCP 服务

将 API 密钥和任何 PinRAG 设置放入 MCP 条目的 env 块中。编辑器启动服务时不会加载 .env 文件。

在聊天中使用

操作	工具
为文件、目录或 URL 建立索引	add_document_tool — 必填 paths：本地路径（PDF、纯文本或 DiscordChatExporter .txt、目录）或 URL（YouTube 视频、播放列表 URL、GitHub 仓库、网页文档站点；也支持直接填写 YouTube 视频 ID）。可选 tags（每个路径对应一个）。仅适用于 GitHub URL：branch、include_patterns、exclude_patterns。
列出已建立索引的文档	list_documents_tool — 返回 documents（ID）、total_chunks，以及可选的 tag 筛选条件。document_details 可能包含 document_type、标签、页数 / 消息数 / 片段数、标题、汇总 bytes，以及元数据中存在时的 upload_timestamp。
使用筛选条件查询	query_tool — 必填 query。可选 document_id、tag、document_type、page_min / page_max（PDF 页码范围）、response_style（thorough 或 concise；留空则使用 PINRAG_RESPONSE_STYLE）。
删除文档	remove_document_tool — 必填 document_id（取自 list_documents_tool 的准确值）。
查看资源（只读）	在 MCP 面板中打开 Resources，并选择 pinrag://documents（已建立索引的文档）或 pinrag://server-config（生效的配置，包括 PINRAG_VERSION）。

在聊天中提问："将 /path/to/amiga-book.pdf 添加进索引，并添加标签 AMIGA"、"为 https://youtu.be/xyz 建立索引，并询问其中的内容"、"为 https://github.com/owner/repo 建立索引，并询问代码库"，或 "为 https://docs.langchain.com/ 建立索引，并总结其记忆 API"。AI 会为你调用这些工具。引用会显示 PDF 的页码、YouTube 的时间戳（例如 t. 1:23）、纯文本和 Discord 导出的文档名称、GitHub 的分块索引标签，以及网页文档的源 URL。

GitHub 索引

使用 add_document_tool 并在 paths 中填写 URL，为仓库建立索引，例如 https://github.com/owner/repo、https://github.com/owner/repo/tree/branch 或 github.com/owner/repo（可省略 scheme）。

仅适用于 GitHub 的选项： branch、include_patterns / exclude_patterns — 默认设置已优先包含常见文本和源代码文件，并跳过较大的文件；需要索引这些范围之外的文件时，请使用匹配模式。超过 PINRAG_GITHUB_MAX_FILE_BYTES（默认值为 512 KiB）的文件会被跳过。

身份验证： 在 MCP env（或 shell）中设置 GITHUB_TOKEN，以访问私有仓库或减少大型索引操作触发速率限制的次数；小型公共仓库通常无需令牌也能正常处理。请使用具有仓库读取权限的 classic 或 fine-grained PAT；PinRAG 不支持 OAuth。

网页文档索引

将 add_document_tool 指向任意文档站点 URL，例如 https://docs.langchain.com/、https://docs.crewai.com/ 或 https://picocomputer.github.io/。PinRAG 会依次通过 llms.txt / llms-full.txt（Mintlify 风格）、sitemap.xml（包括 robots.txt 中的 Sitemap: 提示和嵌套站点地图索引），然后从种子 URL 开始进行限定范围的 BFS 爬取来发现页面。

**范围：**主机名必须完全匹配（不包括子域名），并使用从种子 URL 推导出的路径前缀——例如，https://docs.example.com/guide/ 只会索引 /guide/ 下的页面。使用站点根 URL 可涵盖完整文档树。

提取：text/markdown 响应（来自 llms.txt 快速路径）会直接传递；HTML 则通过 trafilatura 处理，并在失败时回退到 BeautifulSoup + markdownify，且只处理 <main> / <article> / [role=main] 范围内的内容。

限制与礼貌性：由 PINRAG_WEB_MAX_PAGES（默认值为 200）、PINRAG_WEB_MAX_DEPTH（5）、PINRAG_WEB_MAX_PAGE_BYTES（1 MiB）、PINRAG_WEB_CONCURRENCY（4）、PINRAG_WEB_RATE_LIMIT_PER_HOST（2.0/秒）和 PINRAG_WEB_RESPECT_ROBOTS（true）控制。部分站点（例如受 Cloudflare 保护的页面）可能会向纯 Python 客户端返回 403；这是已知限制。

**引用：**网页内容块包含 source_url 元数据字段；回答会按页面 URL 引用，document_id 为 <host><path_prefix>，因此 remove_document_tool / set_document_tag_tool 可一次性对整个站点进行操作。

YouTube 索引与 IP 封锁

大量依赖字幕的索引——尤其是来自云端或高流量 IP 的请求——可能会返回类似 "YouTube is blocking requests from your IP" 的错误。通过 MCP env（或你的 shell）为 youtube-transcript-api 配置代理：

PINRAG_YT_PROXY_HTTP_URL=http://user:[email protected]:80
PINRAG_YT_PROXY_HTTPS_URL=http://user:[email protected]:80

PINRAG_YT_PROXY_* 仅影响字幕获取；yt-dlp 步骤（标题、播放列表）不会使用它。住宅代理或轮换代理通常比原始数据中心 IP 效果更好。

部分路径失败时（例如播放列表中少数视频失败），add_document_tool 会在 fail_summary 中提供失败计数，按 blocked、disabled、missing_transcript 和 other 分类。

YouTube 视觉增强（可选）

默认索引仅处理字幕。设置 PINRAG_YT_VISION_ENABLED=true 可为屏幕上的内容添加视觉字幕，与字幕按时间对齐，并按块添加 has_visual、frame_count 和 visual_source 等元数据。

PINRAG_YT_VISION_PROVIDER：

• openai（默认）或 anthropic：通过 yt-dlp 下载 → 基于场景提取帧 → 每帧进行一次多模态调用。需要 pinrag[vision]、PATH 中的 ffmpeg/ffprobe，以及 OPENAI_API_KEY 或 ANTHROPIC_API_KEY（在与 pinrag 相同的环境中安装额外依赖，例如 uv sync --extra vision 或 pip install 'pinrag[vision]'）。
• openrouter：每个视频通过 video_url 发起一次 OpenRouter 请求（默认使用 google/gemini-2.5-flash）。只需 OPENROUTER_API_KEY——无需下载、ffmpeg 或 pinrag[vision]；覆盖 PINRAG_YT_VISION_MODEL 时，请选择支持视频的模型。

**运维：**更改视觉设置后请重新索引。对于 openai/anthropic，可通过 PINRAG_YT_VISION_MAX_FRAMES 和可选的 PINRAG_YT_VISION_IMAGE_DETAIL=high（小字更清晰，但会消耗更多 token）调整成本和超时。**MCP stdio：**yt-dlp 的进度信息会写入 stderr，使 stdout 保持纯 JSON。下载视频可能违反 YouTube 服务条款或当地规定——请自行决定。**Docker：**使用 BUILD_WITH_VISION=1 构建，以包含 ffmpeg + pinrag[vision]（参见 Dockerfile）。

提示

• 未找到 pinrag： MCP 会继承你的登录 PATH。安装 pipx 或 uv tool install 后，重启编辑器并确认 which pinrag。
• PINRAG_PERSIST_DIR： 在 MCP env 中使用稳定的绝对路径（例如 ~/.pinrag/chroma_db），这样向量存储就不会依赖服务进程的当前工作目录。
• FlashRank： 在同一工具环境中安装 pinrag[rerank]（pipx install 'pinrag[rerank]' / uv tool install 'pinrag[rerank]'）；可调参数见配置。
• YouTube 视觉功能： 按照 YouTube 视觉增强配置环境变量和依赖项；更改视觉设置后，请重新索引。
• pinrag://server-config： MCP 资源 → 此 URI，可查看 PINRAG_VERSION、生效中的 LLM/嵌入/分块设置，以及 API 密钥的已设置 / 未设置状态。

配置

MCP 资源 pinrag://server-config 会显示 PINRAG_VERSION（软件包版本，并非由你设置的环境变量）以及下列变量的生效值，还会显示哪些 API 密钥已设置。请将此表作为完整的环境变量参考。

环境变量：

变量	默认值	说明
大模型（LLM）
提供商和模型
PINRAG_LLM_PROVIDER	openrouter	openrouter、openai、anthropic 或 cerebras
PINRAG_LLM_MODEL	(提供商默认值)	未设置时：OpenRouter 为 openrouter/free，OpenAI 为 gpt-4o-mini，Anthropic 为 claude-haiku-4-5，Cerebras 为 llama3.1-8b。可使用任意模型 ID 覆盖（例如，OpenRouter 使用 anthropic/claude-sonnet-4-6，Cerebras 使用 gpt-oss-120b）。
OpenRouter
PINRAG_OPENROUTER_MODEL_FALLBACKS	(未设置)	以逗号分隔的备用模型 slug 列表，将作为 OpenRouter 的 models 列表发送。主模型（PINRAG_LLM_MODEL）失败时（速率限制、服务中断等），网关会尝试下一个 slug。可在此使用其他免费模型，以保持零成本。旧版别名：PINRAG_LLM_MODEL_FALLBACKS。
PINRAG_OPENROUTER_SORT	(未设置)	可选的 provider.sort，可设为 price、throughput 或 latency。未设置时，OpenRouter 使用默认的提供商选择方式。如果设置了 PINRAG_OPENROUTER_PROVIDER_ORDER 来固定特定后端，建议将此项留空（避免路由信号冲突）。
PINRAG_OPENROUTER_PROVIDER_ORDER	(未设置)	以逗号分隔的 provider.order 提供商名称（按顺序尝试）。例如，将其设为 Cerebras 并设置 PINRAG_LLM_MODEL=openai/gpt-oss-120b，以优先使用 Cerebras-backed routing。请使用 OpenRouter 上该模型提供商列表中的精确标签。
OPENROUTER_APP_URL	https://github.com/ndjordjevic/pinrag	应用归属信息（HTTP-Referer）。可覆盖为你的网站 URL（参见 OpenRouter app attribution）。PinRAG 会将此值复制到 OPENROUTER_HTTP_REFERER，供 OpenRouter Python SDK 使用。
OPENROUTER_APP_TITLE	PinRAG	应用标题（X-Title）。可覆盖此值，以便在 OpenRouter 控制面板中标注用量。PinRAG 会将此值复制到 OPENROUTER_X_OPEN_ROUTER_TITLE，供 SDK 使用。
API 密钥
OPENROUTER_API_KEY	(使用 OpenRouter 作为大模型、评估器或 YouTube 视觉功能提供商时必需)	当 PINRAG_LLM_PROVIDER=openrouter、PINRAG_EVALUATOR_PROVIDER=openrouter，或 YouTube 视觉功能使用 PINRAG_YT_VISION_PROVIDER=openrouter 时必需。
OPENAI_API_KEY	(使用 OpenAI 大模型或 OpenAI YouTube 视觉功能时必需)	当 PINRAG_LLM_PROVIDER=openai，或 PINRAG_YT_VISION_ENABLED=true 且 PINRAG_YT_VISION_PROVIDER=openai 时必需。
OPENAI_BASE_URL	(可选)	覆盖 OpenAI API 基础 URL（例如，使用 OPENAI_API_KEY 设置为你的 OpenRouter 密钥，以通过 https://openrouter.ai/api/v1 进行视觉或其他兼容 OpenAI 的调用）。
CEREBRAS_API_KEY	(使用 Cerebras 大模型时必需)	当 PINRAG_LLM_PROVIDER=cerebras 时必需。请从 Cerebras cloud console 获取密钥。
PINRAG_CEREBRAS_BASE_URL	https://api.cerebras.ai/v1	覆盖 Cerebras 的兼容 OpenAI 基础 URL（例如，专用推理端点）。
ANTHROPIC_API_KEY	(使用 Anthropic 大模型或 Anthropic YouTube 视觉功能时必需)	当 PINRAG_LLM_PROVIDER=anthropic、PINRAG_EVALUATOR_PROVIDER=anthropic，或 YouTube 视觉功能使用 PINRAG_YT_VISION_PROVIDER=anthropic 时必需。
嵌入
PINRAG_EMBEDDING_MODEL	nomic-embed-text-v1.5	本地 Nomic 模型 ID（通过 langchain-nomic）。首次运行时会下载权重（约 270 MB，并缓存）。无需 API 密钥。
存储和分块
PINRAG_PERSIST_DIR	chroma_db	Chroma 向量存储目录（默认路径相对于服务进程的当前工作目录；也可设置绝对路径，例如 ~/.pinrag/chroma_db，以使用固定位置）
PINRAG_CHUNK_SIZE	1000	文本块大小（字符数）
PINRAG_CHUNK_OVERLAP	200	文本块重叠长度（字符数）
PINRAG_STRUCTURE_AWARE_CHUNKING	true	对代码和表格边界应用结构感知分块启发式规则
PINRAG_COLLECTION_NAME	pinrag	Chroma 集合名称。默认使用单个共享集合。
ANONYMIZED_TELEMETRY	setdefault 在未设置时设为 False	Chroma 遥测标志。PinRAG 的 MCP 日志设置会调用 os.environ.setdefault("ANONYMIZED_TELEMETRY", "False")，因此值为空或未设置时均视为选择退出；如果要启用 Chroma 遥测，请在 env 中设为 true。
检索
PINRAG_RETRIEVE_K	20	关闭重排时的检索池大小。启用重排时，如果未设置 PINRAG_RERANK_RETRIEVE_K，则回退到此值，随后将结果截取至 PINRAG_RERANK_TOP_N。
父子检索
PINRAG_USE_PARENT_CHILD	false	设为 true，以嵌入较小的文本块并返回较大的父文本块（支持 PDF、GitHub、YouTube 和 Discord 索引，不支持纯 .txt）。需要重新索引。
PINRAG_PARENT_CHUNK_SIZE	2000	PINRAG_USE_PARENT_CHILD=true 时的父文本块大小（字符数）。
PINRAG_CHILD_CHUNK_SIZE	800	PINRAG_USE_PARENT_CHILD=true 时的子文本块大小（字符数）。
重排
PINRAG_USE_RERANK	false	设为 true 以启用 FlashRank 重排：获取更多文本块，在本地重新评分，再将排名靠前的 N 个传给大模型。需要运行 pip install pinrag[rerank]，且无需 API 密钥。
PINRAG_RERANK_RETRIEVE_K	(继承 PINRAG_RETRIEVE_K)	PINRAG_USE_RERANK=true 时，在 FlashRank 处理前获取的文本块数量。未设置时，等于 PINRAG_RETRIEVE_K（并非单独硬编码为 20）。
PINRAG_RERANK_TOP_N	10	PINRAG_USE_RERANK=true 时，重排后传给大模型的文本块数量（不超过重排前的获取数量）。
多查询
PINRAG_USE_MULTI_QUERY	false	设为 true，通过大模型生成用户查询的替代表述，分别检索后合并（去重并集）。可提升简短或含糊查询的召回率。
PINRAG_MULTI_QUERY_COUNT	4	要生成的替代查询数量（默认值为 4，最多 10 个）。合并检索结果时仍会包含原始查询。
响应风格
PINRAG_RESPONSE_STYLE	thorough	RAG 答案风格：thorough（详细）或 concise。评估目标会使用此设置；MCP query 未指定 response_style 时也会以此为默认值。
MCP 通知
PINRAG_VERBOSE_LOGGING	false	设为 true，为工具或资源执行发送详细的分阶段 MCP 通知（格式检测、转录加载、视觉处理路径或步骤、文本块写入）。默认仅记录简洁的开始、成功和错误生命周期日志。
GitHub 索引
GITHUB_TOKEN	(可选)	GitHub API 个人访问令牌。私有仓库需要此令牌；对公共仓库则可提高速率限制。
PINRAG_GITHUB_MAX_FILE_BYTES	524288 (512 KB)	对 GitHub 仓库建立索引时，跳过大于此值的文件。
PINRAG_GITHUB_DEFAULT_BRANCH	main	GitHub URL 未指定分支时使用的默认分支。
纯文本索引
PINRAG_PLAINTEXT_MAX_FILE_BYTES	524288 (512 KB)	建立索引时跳过大于此值的纯 .txt 文件。
网页文档索引
PINRAG_WEB_MAX_PAGES	200	每次网页索引运行最多获取的页面数。
PINRAG_WEB_MAX_DEPTH	5	从种子 URL 开始的最大 BFS 爬取深度（使用 llms.txt / sitemap 快速路径时忽略）。
PINRAG_WEB_MAX_PAGE_BYTES	1048576 (1 MiB)	跳过响应正文大小超过此值的页面。
PINRAG_WEB_REQUEST_TIMEOUT	20	每次 HTTP 请求的超时时间，单位为秒（连接 + 读取）。
PINRAG_WEB_CONCURRENCY	4	每个主机最多并发获取的数量。
PINRAG_WEB_RATE_LIMIT_PER_HOST	2.0	每个主机的令牌桶补充速率（请求数/秒）。
PINRAG_WEB_USER_AGENT	PinRAGBot/<version> (+https://github.com/ndjordjevic/pinrag)	网页索引使用的 HTTP User-Agent 标头。某些网站会拦截通用机器人；必要时可覆盖此值。
PINRAG_WEB_RESPECT_ROBOTS	true	true / false — 爬取时是否遵守 robots.txt 的禁止规则。
PINRAG_WEB_PREFER_LLMS_TXT	true	在 sitemap / BFS 之前尝试 llms.txt / llms-full.txt。禁用后将强制使用 sitemap 或爬取发现。
YouTube 转录代理
PINRAG_YT_PROXY_HTTP_URL	(无)	获取转录时使用的 HTTP 代理 URL（例如 http://user:pass@proxy:80）。当 YouTube 屏蔽你的 IP 时使用。
PINRAG_YT_PROXY_HTTPS_URL	(无)	获取转录时使用的 HTTPS 代理 URL。使用通用代理时，与 HTTP 代理相同。
YouTube 视觉功能（可选）
PINRAG_YT_VISION_ENABLED	false	设为 true / 1 / yes / on 可启用 YouTube 画面内容增强。openai / anthropic：需要 pinrag[vision]、PATH 中的 ffmpeg，以及对应的 API 密钥。openrouter：只需要 OPENROUTER_API_KEY（原生 video_url 路径；无需本地下载）。
PINRAG_YT_VISION_PROVIDER	openai	openai、anthropic 或 openrouter。独立于 PINRAG_LLM_PROVIDER（RAG 大模型和视觉功能可以使用不同的提供商）。旧版别名：PINRAG_VISION_PROVIDER。
PINRAG_YT_VISION_MODEL	(因提供商而异)	未设置时：OpenAI 为 gpt-4o-mini，Anthropic 为 claude-sonnet-4-6，OpenRouter 为 google/gemini-2.5-flash。请使用具备视觉能力的模型 ID。旧版别名：PINRAG_VISION_MODEL。
PINRAG_YT_VISION_MAX_FRAMES	8	仅适用于下载 + 帧处理路径（openai / anthropic）：场景检测后最多分析的关键帧数量。openrouter 会忽略此设置（单次视频请求）。
PINRAG_YT_VISION_MIN_SCENE_SCORE	27.0	仅适用于下载 + 帧处理路径： PySceneDetect AdaptiveDetector 阈值（值越高 → 切换次数越少）。openrouter 会忽略此设置。
PINRAG_YT_VISION_IMAGE_DETAIL	low	仅适用于 OpenAI 帧处理路径： image_url.detail 可设为 low、high 或 auto。anthropic（完整帧）和 openrouter（video_url）会忽略此设置。
LangSmith（可选）
LANGSMITH_TRACING	(关闭)	设为 true 可将跟踪信息发送到 LangSmith。需要 LANGSMITH_API_KEY。
LANGSMITH_API_KEY	(无)	来自 LangSmith Settings → API keys 的 API 密钥。
LANGSMITH_PROJECT	(LangChain 默认值)	跟踪项目名称（例如 pinrag）。
LANGSMITH_ENDPOINT	美国 API（隐式）	欧盟工作区： 设置为 https://eu.api.smith.langchain.com，让跟踪信息进入你的欧盟项目。如果你的账户在浏览器中使用 eu.smith.langchain.com，则需要设置此项。美国区域的工作区可省略此项（默认 API 主机）。
评估器（LLM-as-judge）
PINRAG_EVALUATOR_PROVIDER	openai	openai、anthropic 或 openrouter — 用于运行 LLM-as-judge 评分器的大模型。仅在评估运行期间（LangSmith 实验）使用。
PINRAG_EVALUATOR_MODEL	(提供商默认值)	用于正确性评分的模型（例如 gpt-4o、claude-sonnet-4-6，或评估器提供商为 OpenRouter 时的 openrouter/free）。使用 OpenRouter 时，默认免费路由器可能会轮换模型；评分器使用严格的 JSON schema — 如果需要稳定的结构化输出，请将此项设为 openrouter.ai/models 中的特定免费 slug。设置 PINRAG_EVALUATOR_PROVIDER=openrouter 时，下方的 OpenRouter 路由环境变量也适用于评分器。
PINRAG_EVALUATOR_MODEL_CONTEXT	(提供商默认值)	用于依据上下文评分的模型（检索到的上下文较长；例如 gpt-4o-mini、claude-haiku-4-5，或评估器提供商为 OpenRouter 时的 openrouter/free）。与 PINRAG_EVALUATOR_MODEL 适用相同的 OpenRouter 说明。评估器提供商为 OpenRouter 时，PINRAG_OPENROUTER_MODEL_FALLBACKS、PINRAG_OPENROUTER_SORT 和 PINRAG_OPENROUTER_PROVIDER_ORDER 均适用于评分器客户端。

**更改嵌入模型时重新索引：**更改 PINRAG_EMBEDDING_MODEL 需要重新索引；向量维度必须与索引时使用的模型一致（包括使用旧版默认嵌入模型创建的索引）。

**启用父子结构时重新索引：**设置 PINRAG_USE_PARENT_CHILD=true 需要重新索引；新结构（Chroma 中的子块、docstore 中的父块）仅会在为受支持的文档类型建立索引时创建（不包括纯 .txt 文件）。

**切换 YouTube 视觉分析时重新索引：**开启或关闭 PINRAG_YT_VISION_ENABLED、更改 PINRAG_YT_VISION_PROVIDER，或更改视觉模型、PINRAG_YT_VISION_IMAGE_DETAIL 或帧数限制，都需要为受影响的 YouTube 文档重新索引，使分块反映新的行为。

监控与可观测性

如需查询性能指标（延迟、耗时、令牌用量）和调试，请使用 LangSmith。在 MCP env 或 shell 中设置 LANGSMITH_TRACING=true 和 LANGSMITH_API_KEY；也可以设置 LANGSMITH_PROJECT（参见上表）。如果你的 LangSmith 工作区位于欧盟区域（你在浏览器中使用 eu.smith.langchain.com），还必须设置 LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com；否则，跟踪记录可能不会显示在欧盟部署中。美国区域账户使用默认 API 主机，无需设置 LANGSMITH_ENDPOINT。详情请参见 notes/langsmith-setup.md。

如需在 MCP 端进行自省，请设置 PINRAG_VERBOSE_LOGGING=true，以便在 notifications/message 中显示详细的阶段事件（例如 YouTube 转录文本加载、是否运行视觉分析，以及分块写入进度）。

多个提供方和集合

每个 Chroma 集合的向量维度都是固定的，必须与写入分块时使用的 PINRAG_EMBEDDING_MODEL 一致。默认 ID nomic-embed-text-v1.5 是一个 768 维的 Nomic 模型；其他 PINRAG_EMBEDDING_MODEL 值可能对应不同的维度，具体请查阅相应模型的文档。

• 默认设置：PINRAG_COLLECTION_NAME 默认为 pinrag。对于已有集合，不要在未重新索引到新集合（或清空旧集合）的情况下更改 PINRAG_EMBEDDING_MODEL；否则，添加或查询可能会因嵌入维度错误而失败。
• 每个模型使用独立集合：为每个索引使用一组稳定配对的 PINRAG_EMBEDDING_MODEL + PINRAG_COLLECTION_NAME（如果要隔离存储，还包括 PINRAG_PERSIST_DIR）。查询集合时，设置与索引时相同的环境变量。你可以使用另一组配对为相同来源重新建立索引（更改 env，必要时重启 MCP，然后运行 add_document_tool）。
• MCP 工具：默认情况下，每个工具都会使用 config.get_persist_dir() 和 config.get_collection_name()；工具调用中的可选参数 collection 会覆盖该请求的集合名称。list_collections_tool 会列出已配置持久化目录中的集合名称（可选使用 persist_dir 覆盖）。

MCP 参考

pinrag MCP 服务（FastMCP("PinRAG")）提供的工具、提示词和只读资源。工具结果是 JSON 对象，始终包含 _server_version；设置 PINRAG_VERBOSE_LOGGING=true 时，结果还可能包含 _verbose_log。

add_document_tool 会返回 indexed、failed、计数、persist_directory、collection_name，以及在任何路径失败时返回 fail_summary。query_tool 会返回 answer 和 sources（每个条目包含 document_id、page——PDF 页码，非 PDF 文档通常为 0——以及可选的 YouTube 起始时间 start，单位为秒）。

query_tool

自然语言问题；可选筛选条件可缩小检索范围（未使用时传入 "" / 省略）：

参数	描述
query	问题（必填）
document_id	限定为此文档 — 使用 list_documents_tool 返回的精确引用、列表标题或唯一的 PDF 文件名（不含扩展名）
page_min, page_max	PDF 页码范围（含边界；必须同时传入；单页查询：同一页码传两次）
tag	仅包含带此标签的分块
document_type	pdf、youtube、discord、github、plaintext 或 web
response_style	thorough 或 concise。为空（架构默认值）或为其他任何字符串时 → 通过 PINRAG_RESPONSE_STYLE 解析（参见 server.py：只有这两个字面值会覆盖环境变量）。

筛选条件可以组合使用。sources 列表对 PDF 使用 page，对 YouTube 使用 start（秒）；答案可能会显示根据 start 生成的 t. M:SS 标签。GitHub 引文在答案文本中使用类似分块索引的 p. N 标签。Web 文档来源会携带每页对应的 source_url。

示例："What is OpenOCD? In the Pico doc, pages 16–17 only" → query_tool(query="What is OpenOCD?", document_id="RP-008276-DS-1-getting-started-with-pico.pdf", page_min=16, page_max=17)。

add_document_tool

为本地文件（PDF、纯文本或 Discord .txt、目录）、YouTube（视频 URL、播放列表 URL 或纯 ID）、GitHub URL（可省略协议）或 Web 文档站点（任意 http(s) URL）建立索引。paths 会批量处理项目；某个路径失败不会回滚其他项目。仅持久化到 PINRAG_PERSIST_DIR / PINRAG_COLLECTION_NAME（没有用于设置这些值的 MCP 参数）。

参数	描述
paths	必填列表：文件、目录、URL 或视频 ID
tags	可选；每个 paths 条目对应一个，顺序相同
branch	仅限 GitHub：覆盖分支
include_patterns	仅限 GitHub：glob 包含模式列表
exclude_patterns	仅限 GitHub：glob 排除模式列表

list_documents_tool

返回 documents、total_chunks、persist_directory、collection_name 和 document_details（标签、标题、数量、存在时的汇总 bytes、upload_timestamp 等）。如果设置了 tag，total_chunks 仅统计带该标签的分块（而非整个集合）。

参数	描述
tag	可选：仅列出带有此标签的文档

remove_document_tool

删除 document_id 对应的所有分块。可使用 list_documents_tool 返回的精确引用、列表标题或唯一的 PDF 文件名（不含扩展名）。

参数	描述
document_id	必填 — 精确引用、列表标题或唯一的 PDF 文件名（不含扩展名）

set_document_tag_tool

为某个文档的所有已索引分块设置或替换 tag。可在建立索引后添加或更正标签，无需重新建立索引。文档定位规则与 remove_document_tool 相同。

参数	描述
document_id	必填 — 精确引用、列表标题或唯一的 PDF 文件名（不含扩展名）
tag	必填 — 非空标签字符串
collection	可选覆盖项（默认值：PINRAG_COLLECTION_NAME）

MCP 提示词：use_pinrag

内置路由说明：request 会作为第一行插入；其余内容列出各工具的适用场景及其参数（与 server.py 中的 use_pinrag 一致）。客户端提供 MCP 提示词的任何位置都可以查看（例如 Cursor）。

参数	描述
request	可选的用户目标（可以为空）

MCP 资源

资源	描述
pinrag://documents	服务器配置集合的纯文本列表（来自 format_documents_list）
pinrag://server-config	有效环境变量/配置的可打印转储（包括 PINRAG_VERSION、关键运行变量、API 密钥是否存在）

运行测试

在仓库根目录安装开发额外依赖（例如 uv sync --extra dev）。

• 快速测试（不包含 integration）：
  uv run pytest tests/ -q -m "not integration"
  跳过 pyproject.toml 中标记为 integration 的测试（网络、API 密钥、可选资源、MCP 标准输入/输出）。任何使用 sample_pdf_path fixture 的测试都会在 tests/conftest.py 中自动添加该标记，因此只有完整测试才需要 data/pdfs/ 下的示例 PDF。

• 完整测试套件：
  uv run pytest tests/ -q

  **密钥：**对于 MCP 标准输入/输出测试，子进程环境变量从你的 shell 环境开始，然后从 tests/.mcp_stdio_integration.env 补充任何缺失的 OPENAI_API_KEY / ANTHROPIC_API_KEY（从 tests/mcp_stdio_integration.env.example 复制；只会从文件中读取这些密钥——已设置的环境变量优先）。使用 PINRAG_MCP_ITEST_ENV_FILE 覆盖该文件。合并后，test_mcp_stdio_repo.py 要求设置 OPENAI_API_KEY，并且 PINRAG_LLM_PROVIDER 必须通过其凭证检查（例如，使用 OpenRouter 时导出 OPENROUTER_API_KEY）。test_mcp_stdio_pypi.py 也需要可用的 OpenAI 密钥。

  **PDF / 标准输入/输出：**默认 PDF 为 data/pdfs/sample-text.pdf（不在 git 中）。使用 PINRAG_MCP_ITEST_PDF / PINRAG_MCP_ITEST_QUERY 覆盖。标准输入/输出测试需要 PATH 中有 uv，或将 PINRAG_TEST_UV 设为二进制文件路径。

  **PyPI MCP 测试：**标记为 pypi_mcp；使用 -m "not pypi_mcp" 或 PINRAG_MCP_ITEST_SKIP_PYPI=1 跳过。使用 PINRAG_MCP_ITEST_PYPI_SPEC 固定安装版本（默认 pinrag = PyPI 上的最新版本）。

  详细日志：--log-cli-level=INFO。

data/ 目录被 git 忽略——在本地创建 data/pdfs/（及类似目录）；data/ 下的内容都不会提交。

许可证

MIT 许可证。完整文本见 LICENSE。