Open Scout

OpenScout

OpenScout是一个以开发人员为中心的检索增强生成（RAG）\[困惑类型架构\]，具有MCP集成和Neo4j适配器。

它通过搜索网络、获取和提取页面内容、分块和嵌入段落、将向量存储在FAISS中、检索最相关的段落、对它们进行重新排序，以及使用可插拔的LLM适配器合成简洁的引用答案来回答自然语言问题。

______________________________________________________________________

建筑

高级组件和运行时流程：

• UI（Streamlit）-接受用户查询，处理侧栏中的API键（BYOK），并显示聊天风格的答案和来源。
• MCP层(core/mcp)--可选：配置后，应用程序调用中央MCP服务器进行搜索/提取/密码；否则，它将退回到本地SDK（Tavily/Neo4j）。
• 图形管道(core/graph.py)--编排节点：搜索→ 获取→ 索引→ 检索。它返回检索到的点击进行合成。
• 费彻(core/fetch.py)--下载页面并提取文本（httpx+trafilatura）。
• 填充+嵌入(core/chunk.py, core/embed.py)--将文本拆分为段落并计算嵌入（默认为OpenAI）。
• 矢量存储(core/faiss_store.py)--FAISS索引（IndexIDMap+IndexFlatIP）+段落的SQLite元数据。
• 重新排名(core/rerank.py)--可选交叉编码器，精度更高。
• 合成器(core/synthesize.py)--从顶部段落构建提示，并调用所选的LLM适配器（在可用时支持流式传输）。

运行时流程：用户查询→ 搜索（MCP或Tavily）→ 获取页面→ 块和嵌入→ 索引/存储→ 检索顶部通道→ （重新排序）→ LLM合成→ UI.

Architecture

文件

关键文件及其用途：

• app.py --流线型入口点；UI、BYOK处理、每个提供者的密钥测试、聊天历史和图的编排。
• core/graph.py --LangGraph状态图连接主管道节点（搜索、获取、索引、检索）并绑定合成器。
• core/mcp/adapters.py --MCPTools适配器：配置后调用远程MCP服务器(MCP_URL)或者回退到本地SDK（Tavily/Neo4j）。
• core/search.py --本地Tavily搜索包装器，错误消息更清晰。
• core/fetch.py --使用httpx和通过trafilatura进行内容提取的异步提取器。
• core/chunk.py --文本分块逻辑，用于将页面拆分为段落大小的块。
• core/embed.py --OpenAI嵌入包装器（接受显式密钥或使用 OPENAI_API_KEY env回退）。
• core/faiss_store.py --FAISS索引管理（创建/包装IndexIDMap）和块的SQLite元数据存储。
• core/rerank.py --使用句子变换器的基于交叉编码器的重排序器（可选）。
• core/llm/ --LLM适配器和注册表(openai_llm.py, anthropic_llm.py, gemini_llm.py, groq_llm.py, registry.py).
• core/synthesize.py --根据检索到的段落构建提示，并通过LLM适配器执行合成。

______________________________________________________________________

截图

示例运行中的UI截图（单击查看完整尺寸）：

• 主聊天+答案视图

OpenScout chat view

• 来源面板

Sources

• 侧板

Side Panel

______________________________________________________________________

如何使用这个

在本地运行OpenScout的快速步骤（PowerShell命令）。这些说明假设您已安装Python 3.10+。

提示：对于交互式本地使用，请在应用程序运行时将您的LLM和提供商API密钥粘贴到Streamlit侧栏中-这将使您的回购保密。创造一个 .env 是可选的，仅建议用于持久的本地默认值或CI。

1. 克隆或下载存储库：

git clone  
cd OpenScout

1. 创建并激活虚拟环境，然后安装依赖项。如果你已经有了 requirements.txt 使用它；否则，从您的环境中创建一个。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Note- First query may download ~90MB model

1. 获取凭据：

• Neo4j：URI、用户名和密码（如果您计划使用Neo4j进行图形/密码操作）。
• 塔维利： TAVILY_API_KEY 用于网络搜索/丰富（或配置MCP服务器）。
• LLM提供者密钥：其中之一 OPENAI_API_KEY, GROQ_API_KEY, ANTHROPIC_API_KEY，或 GOOGLE_API_KEY （双子座）。

1. 创建一个 .env 项目根目录中带有凭据的文件（示例）——或者，对于交互式使用，在运行时将密钥粘贴到Streamlit侧边栏字段中（首选用于本地测试）。侧边栏在会话中存储密钥； .env 是可选的，主要用于CI或需要持久的本地默认值时。

TAVILY_API_KEY=tvly...
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=yourpassword
OPENAI_API_KEY=sk-...      # or GROQ_API_KEY=grq-... , ANTHROPIC_API_KEY=..., GOOGLE_API_KEY=...
# Optional: MCP_URL and MCP_API_KEY if using a remote MCP server
# MCP_URL=https://your-mcp.server
# MCP_API_KEY=...

1. 启动Streamlit应用程序：

streamlit run .\app.py

1. 在应用侧边栏中：

• 将任何缺失的密钥粘贴到相应的字段中（它们将存储在会话中）。
• （可选）单击每个提供程序的“测试密钥”按钮以验证连接。

1. 在聊天输入中提问。该应用程序将搜索、获取页面、索引段落并合成引用的答案。

注意事项和故障排除：

• 如果您看到以下包的导入错误 faiss, torch，或 tavily，安装正确的操作系统特定车轮或使用 faiss-cpu 对于大多数本地开发设置。
• 如果由于索引类型导致FAISS索引加载失败，请删除现有的 faiss_index.bin 以允许重建或运行迁移脚本（不包括在内）。
• 在提交中保守秘密：确保 .env 在...里 .gitignore.