searxng-ai-kit

# SearXNG AI 工具包 **适用于终端、代码和 AI 助手的 AI 增强搜索** SearXNG AI 工具包是一个 AI 增强的命令行界面、Python 库和 MCP 服务器，适用于 SearXNG 隐私保护元搜索引擎。通过 AI 助手研究主题，从终端搜索网络，集成到 Python 项目中，或与 AI 助手连接，支持 180 多个搜索引擎。 ## 功能 🔍 **命令行工具** - 从终端搜索，具有 AI 增强的研究能力 🤖 **AI 聊天** - 提出问题并使用 180 多个搜索引擎获取全面研究 🐍 **Python 库** - 程序化搜索和 AI 驱动的内容检索 🔌 **MCP 服务器** - AI 助手集成，具有高级研究工具 📦 **独立二进制文件** - 为 Linux 和 macOS 预构建的可执行文件 ## 安装 ### 下载独立二进制文件（推荐） 推荐的安装路径是从 [GitHub 发布页面](https://github.com/nikvdp/searxng-ai-kit/releases) 下载适用于您平台的预构建二进制文件。 源安装路径需要构建和供应商特定的 SearXNG 轮子，然后 CLI 才能运行，因此比普通的 `uv tool install` 更慢，涉及更多步骤。除非您正在开发该项目或故意更新固定的上游 SearXNG 版本，否则请使用二进制文件。 目前，发布二进制文件仅适用于 Linux 和 macOS。Windows 二进制文件暂时禁用，因为当前的 pybin Windows 包启动器尚未原生。 下载后，使二进制文件可执行并将其放在您的 `PATH` 中： ```bash chmod +x searxng-ai-kit-* ./searxng-ai-kit-* --help ``` ### 从源代码安装（高级） 当您想要开发项目、检查供应商的 SearXNG 构建或更新固定的 SearXNG 提交时，请使用此路径。 先决条件： - Python 3.11+ - [uv](https://docs.astral.sh/uv/getting-started/installation/) ```bash # 在 macOS 和 Linux 上 curl -LsSf https://astral.sh/uv/install.sh | sh git clone https://github.com/nikvdp/searxng-ai-kit cd searxng-ai-kit # 构建固定的 SearXNG 轮子并设置本地环境 uv run python dev-setup.py # 作为 uv 工具安装 uv tool install . # 验证 searxng --help ``` ### 开发设置 ```bash # 克隆并设置为开发 git clone https://github.com/nikvdp/searxng-ai-kit cd searxng-ai-kit # 构建 SearXNG 轮子，生成配置文件，同步依赖项 python dev-setup.py # 测试 uv run searxng search "test" --engines duckduckgo ``` 构建系统自动： - 通过 uv 安装 Python 3.11+ - 构建 SearXNG 轮子，具有适当的依赖隔离 - 处理现代类型注释（`str | Exception`） - 生成本地配置文件 ## 用例 ### 基本搜索 ```bash # 使用默认引擎进行简单搜索 searxng search "python 教程" # 使用特定引擎搜索 searxng search "机器学习" --engines duckduckgo,startpage # 在特定类别中搜索 searxng search "神经网络" --category science ``` ### 引擎管理 ```bash # 列出所有可用引擎（紧凑概述） searxng engines # 仅列出常用引擎（干净的 4 列布局） searxng engines --common # 列出特定类别中的引擎 searxng engines --category general # 列出类别中仅有的常用引擎 searxng engines --category general --common # 禁用特定引擎进行搜索 searxng search "网页开发" --disable google,bing ``` ### 输出格式 ```bash # 人类可读输出（默认） searxng search "AI 研究" # 用于脚本的 JSON 输出 searxng search "数据科学" --format json # 使用特定引擎的 JSON 输出 searxng search "Rust 编程" --engines duckduckgo --format json > results.json ``` ### 高级选项 ```bash # 搜索具有语言偏好 searxng search "教程 Python" --lang fr # 启用安全搜索 searxng search "编程" --safe 1 # 仅搜索最近的结果 searxng search "科技新闻" --time week --category news # 搜索特定页面 searxng search "JavaScript" --page 2 ``` ### URL 内容检索 ```bash # 从单个 URL 获取内容 searxng fetch-urls "https://example.com" # 并行从多个 URL 获取内容 searxng fetch-urls "https://site1.com" "https://site2.com" "https://site3.com" # 人类可读输出（默认） searxng fetch-urls "https://example.com" # 用于脚本的 JSON 输出 searxng fetch-urls "https://docs.python.org" --format json > content.json # 控制并发以限制速率 searxng fetch-urls url1 url2 url3 --concurrent 2 ``` ### 浏览可用选项 ```bash # 列出所有搜索类别 searxng categories # 获取任何命令的帮助 searxng search --help searxng engines --help ``` ## 可用类别 - **general** - 通用网络搜索（51 个引擎） - **images** - 图片搜索（34 个引擎） - **videos** - 视频搜索（29 个引擎） - **news** - 新闻搜索（18 个引擎） - **science** - 科学出版物（9 个引擎） - **it** - IT/编程资源（44 个引擎） - **music** - 音乐搜索（10 个引擎） - **files** - 文件搜索（17 个引擎） - **maps** - 地图搜索（3 个引擎） - 还有更多... ## 常用引擎 ⭐ **最受欢迎：** - `duckduckgo` - 注重隐私的搜索 - `startpage` - Google 结果，无跟踪 - `brave` - 独立搜索索引 - `google` - Google 搜索 - `bing` - 微软搜索 - `qwant` - 欧洲搜索引擎 ## 测试 CLI ### 测试基本功能 ```bash # 测试类别列表 uv run searxng categories # 或：searxng categories # 测试干净的引擎列表（显示 4 列中的热门引擎） uv run searxng engines --common # 或：searxng engines --common # 测试引擎概述（紧凑的类别摘要） uv run searxng engines # 或：searxng engines # 测试简单搜索 uv run searxng search "测试查询" --engines duckduckgo # 或：searxng search "测试查询" --engines duckduckgo ``` ### 测试不同输出格式 ```bash # 测试人类可读输出 uv run searxng search "Python" --engines duckduckgo | head -20 # 或：searxng search "Python" --engines duckduckgo | head -20 # 测试 JSON 输出 uv run searxng search "编程" --engines duckduckgo --format json | jq . # 或：searxng search "编程" --engines duckduckgo --format json | jq . ``` ### 测试多个引擎 ```bash # 测试多个引擎 uv run searxng search "网页开发" --engines duckduckgo,startpage # 或：searxng search "网页开发" --engines duckduckgo,startpage # 测试引擎过滤 uv run searxng search "JavaScript" --category general --disable google,bing # 或：searxng search "JavaScript" --category general --disable google,bing ``` ### 测试类别 ```bash # 测试不同类别 uv run searxng search "机器学习" --category science --engines arxiv # 或：searxng search "机器学习" --category science --engines arxiv uv run searxng search "React 教程" --category it --engines github # 或：searxng search "React 教程" --category it --engines github uv run searxng search "搞笑猫" --category images --engines duckduckgo_images # 或：searxng search "搞笑猫" --category images --engines duckduckgo_images ``` ## 构建可执行文件（可选） 要创建独立的可执行文件： ```bash # 同步开发依赖项（包括 PyInstaller） uv sync # 使用 PyInstaller 构建（无代码签名） uv run pyinstaller searxng.spec # 测试可执行文件 ./dist/searxng --help ./dist/searxng search "测试" --engines duckduckgo ``` ### 代码签名（仅限 macOS） 对于 macOS 上的分发，您可以可选地启用代码签名，如果您有有效的开发者 ID 证书： ```bash # 设置代码签名的环境变量 export PYINSTALLER_CODESIGN_IDENTITY="Developer ID Application: 您的名字" export PYINSTALLER_ENTITLEMENTS_FILE="entitlements.plist" # 可选 # 使用代码签名构建 uv run pyinstaller searxng.spec ``` **注意：** 可执行文件可能会出现一些引擎加载问题。建议使用 Python 版本以获得完整功能。 ## AI 助手集成 SearXNG AI 工具包包括一个 AI 助手功能，它将网络搜索能力与强大的语言模型相结合。助手可以执行并行搜索并从多个 URL 获取内容，以提供全面研究和答案。 ### Ask 命令（一键问答） ```bash # 使用默认模型提问 searxng ask "量子计算的最新发展是什么？" # 使用注册表中的模型 searxng ask "研究可再生能源趋势" --model "opencode/big-pickle" # 直接使用 LiteLLM 模型字符串 searxng ask "解释 AI" --model "openai/gpt-4o-mini" # 获取用于编程的 JSON 输出 searxng ask "比较 Python 和 JavaScript" --format json # 从 stdin 读取提示以提问更长的问题 echo "分析全球可再生能源采用的当前状态，包括最近的政策变化和技术突破" | searxng ask # 交互式 stdin 模式 searxng ask # （然后输入问题并按 Ctrl+D） # 从文件中读取 searxng ask < my_research_question.txt ``` ### Chat 命令（交互式对话） ```bash # 启动交互式聊天会话（使用默认模型） searxng chat # 使用注册表中的模型 searxng chat --model "opencode/glm-4.7" # 直接使用 LiteLLM 模型字符串 searxng chat --model "openai/gpt-4o-mini" # 使用 OpenRouter 模型 searxng chat --model "openrouter/anthropic/claude-3.5-sonnet" # 使用自定义 API 端点 searxng chat --base-url "https://api.openai.com/v1" ``` 聊天命令维护对话历史，允许后续问题： ``` 您：东京的天气怎么样？ 助手：[搜索当前东京天气信息] 您：明天怎么样？ 助手：[记住我们在讨论东京天气并搜索明天的预报] 您：我应该穿什么？ 助手：[根据前面的搜索信息提供服装建议] ``` **聊天功能：** - **对话记忆**：记住会话中的所有前一条消息 - **上下文感知**：引用对话的前面部分 - **聊天历史**：自动将对话保存到 Markdown 文件 - **模型显示**：显示模型名称（例如 `o3`）而不是通用“助手” - **进度指示器**：等待 AI 响应时的动画旋转器 - **退出命令**：输入 `exit`、`quit`、`bye` 或按 Ctrl+C 结束 - **网络搜索**：在对话期间完全访问搜索工具 - **工具可见性**：实时显示搜索查询和 URL 获取 **聊天历史位置：** - 保存到：`~/.local/share/searxng-ai-kit/chats/`（XDG Base Directory 规范） - 格式：`chat-YYYY-MM-DD_HH-MM-SS-modelname.md` - 示例：`chat-2025-06-29_14-30-15-o3.md` ### 模型注册表 SearXNG AI 工具包使用模型注册表来管理 AI 模型配置。可以导入和使用的模型来自各种提供商，名称简单。 #### 列出可用模型 ```bash # 列出注册表中的所有模型 searxng models list # 显示特定模型的详细信息 searxng models show "opencode/big-pickle" ``` #### 设置默认模型 ```bash # 设置默认模型（在未指定 --model 时使用） searxng models set-default "opencode/big-pickle" # 显示当前默认模型 searxng models set-default ``` #### 从 OpenCode 导入 如果您使用 [OpenCode](https://opencode.ai)，您可以导入已配置的模型： ```bash # 预览将导入的内容 searxng models import opencode --dry-run # 从 OpenCode 配置导入模型 searxng models import opencode ``` 这会从 `~/.config/opencode/opencode.jsonc` 和 `~/.local/share/opencode/auth.json` 导入模型。 #### 使用模型 ```bash # 使用注册表中的模型 searxng ask "什么是量子计算？" --model "opencode/big-pickle" # 在聊天中使用 searxng chat --model "opencode/glm-4.7" # 如果设置了默认值，只需运行而不带 --model searxng ask "解释机器学习" ``` `--model` 标志接受： - **注册名称**：`opencode/big-pickle`，`cli-proxy-api/claude-sonnet-4` - **LiteLLM 字符串**：`openai/gpt-4o`，`anthropic/claude-3-5-sonnet` #### 手动模型管理 ```bash # 手动添加模型 searxng models add "my-model" --type openai --model-id gpt-4o --api-key "sk-..." # 删除模型 searxng models remove "my-model" # 直接编辑模型文件 searxng models edit ``` 模型存储在 `~/.config/searxng/models.toml` 中。 ### API 密钥配置 设置以下环境变量之一（用于模型未存储 API 密钥时）： ```bash # OpenAI（推荐） export OPENAI_API_KEY="您的 OpenAI 密钥" # OpenRouter（访问多个模型） export OPENROUTER_API_KEY="您的 OpenRouter 密钥" # Anthropic export ANTHROPIC_API_KEY="您的 Anthropic 密钥" # Google export GOOGLE_API_KEY="您的 Google 密钥" ``` ### OpenRouter 集成 OpenRouter 通过单个 API 提供对多个 AI 模型的访问。SearXNG 工具包具有原生的 OpenRouter 支持： ```bash # 设置 OpenRouter API 密钥 export OPENROUTER_API_KEY="您的 OpenRouter 密钥" # 使用原生前缀使用 OpenRouter 模型 searxng ask "分析市场趋势" --model "openrouter/openai/gpt-4o-mini" searxng ask "技术研究" --model "openrouter/anthropic/claude-3.5-sonnet" # 使用自定义基本 URL（替代方法） searxng ask "问题" --base-url "https://openrouter.ai/api/v1" --model "openai/gpt-4o-mini" ``` ### CLI 代理 API 集成 SearXNG AI 工具包与 [CLI 代理 API](https://github.com/router-for-me/CLIProxyAPI) 集成，通过他们的 OAuth 和订阅计划提供对多个 AI 提供商的访问 - **无需 API 密钥！** 使用您现有的 Claude Pro、ChatGPT Plus 或 Gemini Advanced 订阅。 #### 步骤 1：安装 CLI 代理 API 从 GitHub 下载最新版本： ```bash # macOS（Apple Silicon） curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-darwin-arm64 -o cli-proxy-api chmod +x cli-proxy-api sudo mv cli-proxy-api /usr/local/bin/ # macOS（Intel） curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-darwin-amd64 -o cli-proxy-api chmod +x cli-proxy-api sudo mv cli-proxy-api /usr/local/bin/ # Linux（x64） curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-linux-amd64 -o cli-proxy-api chmod +x cli-proxy-api sudo mv cli-proxy-api /usr/local/bin/ ``` 或从源代码构建：https://github.com/router-for-me/CLIProxyAPI #### 步骤 2：创建配置文件 创建 `~/.cli-proxy-api/config.yaml`： ```yaml host: "127.0.0.1" port: 8317 auth-dir: "~/.cli-proxy-api" ``` #### 步骤 3：与 AI 提供商身份验证 登录您要使用的提供商： ```bash # Claude（Anthropic）- 打开浏览器进行 OAuth cli-proxy-api -claude-login # Google Gemini - 打开浏览器进行 OAuth cli-proxy-api -login # OpenAI Codex - 打开浏览器进行 OAuth cli-proxy-api -codex-login # Qwen - 打开浏览器进行 OAuth cli-proxy-api -qwen-login ``` 每个登录都会打开您的浏览器进行 OAuth 身份验证。身份验证后，令牌存储在 `~/.cli-proxy-api/` 中。 #### 步骤 4：配置 SearXNG 告诉 SearXNG 您的 CLI 代理 API 配置文件位置： ```bash # 指向您的配置文件 searxng cli-proxy-api set-config ~/.cli-proxy-api/config.yaml # 启用集成 searxng cli-proxy-api enable # 验证所有功能是否正常 searxng cli-proxy-api status ``` #### 步骤 5：设置默认模型（可选） ```bash # 设置默认模型，以便您不必每次都使用 --model searxng cli-proxy-api set-default-model claude-sonnet-4-5-20250929 # 现在只需运行，无需 --model searxng ask "AI 有什么新进展？" searxng chat ``` #### 步骤 6：使用它！ ```bash # 列出所有可用模型 searxng models # 使用 CLI 代理 API 模型（使用显式模型） searxng ask --model cli-proxy-api/claude-sonnet-4-5-20250929 "解释量子计算" # 或仅使用默认值（如果设置） searxng ask "AI 最新进展如何？" # 启动交互式聊天 searxng chat ``` #### 可用命令 ```bash # 列出所有可用模型（显示默认值） searxng models # 检查状态 searxng cli-proxy-api status # 设置/清除默认模型 searxng cli-proxy-api set-default-model claude-sonnet-4-5-20250929 searxng cli-proxy-api clear-default-model # 启用/禁用集成 searxng cli-proxy-api enable searxng cli-proxy-api disable # 设置配置文件路径（如果不在默认位置） searxng cli-proxy-api set-config /path/to/config.yaml # 清除显式配置（使用自动检测） searxng cli-proxy-api clear-config ``` #### 工作原理 当您使用 `cli-proxy-api/*` 模型时： 1. SearXNG 在随机端口上自动启动一个受管理的 cli-proxy-api 子进程 2. 您的 OAuth 令牌（由 cli-proxy-api 存储）处理身份验证 3. 请求通过本地代理路由到 AI 提供商 4. 代理处理令牌刷新和提供商特定的怪癖 **支持的提供商：** - **Anthropic Claude** （通过 OAuth）- claude-sonnet-4-5，claude-opus-4 等 - **Google Gemini** （通过 OAuth）- gemini-2.5-pro，gemini-2.5-flash 等 - **OpenAI** （通过 OAuth）- gpt-4o，gpt-4o-mini 等 - **Alibaba Qwen** （通过 OAuth） - 任何 OpenAI 兼容的提供商（通过配置） ### 自定义 API 端点 使用自定义 OpenAI 兼容端点： ```bash # 通过环境变量 export OPENAI_BASE_URL="https://api.openai.com/v1" searxng ask "问题" # 通过命令行标志（覆盖环境变量） searxng ask "问题" --base-url "https://custom-endpoint.com/v1" ``` ### 可用的 AI 工具 助手可以访问这些工具进行研究： - **web_search**：使用 SearXNG 的 180 多个引擎进行搜索 - **multi_web_search**：并行运行多个搜索 - **fetch_url**：从单个 URL 提取内容 - **fetch_urls**：同时从多个 URL 获取内容 ## MCP 服务器集成 SearXNG AI 套件包含一个用于 AI 应用集成的模型上下文协议（MCP）服务器。这允许像 Claude 这样的 AI 助手直接搜索网络并获取 URL 内容。 ### 启动 MCP 服务器 ```bash # 启动 MCP 服务器（运行直到 Ctrl+C） searxng mcp-server ``` ### 可用的 MCP 工具 1. **网页搜索**: 使用 SearXNG 的 180 多个搜索引擎进行搜索 - 支持所有搜索参数（查询、类别、引擎、语言等） - 返回结构化的 JSON 结果 2. **多重网页搜索**: 并行运行多个搜索查询 - 同时执行多个搜索以获得全面覆盖 - 比顺序搜索更快，适用于研究任务 3. **获取网址内容**: 使用 Jina.ai 获取和提取单个网址的内容 - 清洁的文本提取和内容处理 4. **获取多个网址内容**: 并行获取和提取多个网址的内容 - 使用数组时保持结果顺序 - 优雅地处理错误，同时保留部分结果 5. **提问**: 使用具有上述所有工具访问权限的 AI 助手 - 默认使用 OpenAI o3 模型 - 可以递归使用搜索和网址获取工具 - 支持通过参数自定义模型和基本网址 ### Claude 桌面配置 将以下内容添加到您的 `claude_desktop_config.json`： ```json { "mcpServers": { "searxng": { "command": "searxng", "args": ["mcp-server"] } } } ``` ### 环境变量 - `JINA_API_KEY`: 用于增强 Jina.ai 网址读取功能的 API 密钥（可选） ## 故障排除 ### 常见问题 1. **无搜索结果**: - 尝试不同的引擎： `--engines duckduckgo,startpage` - 检查引擎是否可用： `searxng engines --common` 2. **输出中的引擎错误**: - 正常行为 - 某些引擎可能无法初始化 - 错误打印到 stderr，结果打印到 stdout 3. **搜索速度慢**: - 首次运行正常（引擎初始化） - 使用较少的引擎： `--engines duckduckgo` 而不是默认值 ### CLI 代理 API 问题 **"cli-proxy-api 未找到"** - 安装 cli-proxy-api： https://github.com/router-for-me/CLIProxyAPI - 确保它在您的 PATH 中 **"未找到 cli-proxy-api 配置"** - 在 `~/.cli-proxy-api/config.yaml` 处创建配置 - 或设置路径： `searxng cli-proxy-api set-config /path/to/config.yaml` **"启动 cli-proxy-api 失败"** - 检查配置语法： `cli-proxy-api -config ~/.cli-proxy-api/config.yaml` - 检查端口冲突 **"无可用模型"** - 运行 OAuth 登录： `cli-proxy-api -login` - 检查配置是否有有效凭证 - 尝试 `searxng cli-proxy-api status` 查看详细状态 ### 性能提示 - 使用 `--engines` 指定快速可靠的引擎 - 重定向 stderr 以隐藏引擎错误： `2>/dev/null` - 使用 JSON 格式进行编程使用 ## 示例脚本 ### 搜索并保存结果 ```bash #!/bin/bash query="$1" searxng search "$query" --format json --engines duckduckgo,startpage > "results_$(date +%Y%m%d_%H%M%S).json" ``` ### .bashrc 的快速搜索功能 ```bash search() { searxng search "$*" --engines duckduckgo 2>/dev/null } ``` ## Python 库用法 SearXNG AI 套件也可以在您的项目中作为 Python 库使用： ```python import searxng # 基本搜索 results = searxng.search("python tutorial", max_results=10) print(f"找到 {results['total_results']} 个结果") # 获取网址内容 content = searxng.fetch_url("https://example.com") if content["success"]: print(f"标题： {content['title']}") # 使用具有网页搜索访问权限的 AI 助手提问 response = searxng.ask("量子计算的最新发展是什么？") if response["success"]: print(response["response"]) # 使用自定义模型提问 response = searxng.ask( "研究可再生能源趋势", model="openrouter/openai/gpt-4o-mini" ) # 并行获取网址内容 urls = ["https://site1.com", "https://site2.com"] contents = searxng.fetch_urls(urls, max_concurrent=3) # 使用具有默认设置的客户端 client = searxng.SearXNGClient( default_engines=["duckduckgo", "startpage"], default_max_results=15 ) results = client.search("机器学习") ai_response = client.ask("解释机器学习基础知识") ``` ### 库 API - `searxng.search(query, **kwargs)` - 可自定义参数的网页搜索 - `searxng.fetch_url(url)` - 从单个网址提取内容 - `searxng.fetch_urls(urls, max_concurrent=5)` - 并行网址内容提取 - `searxng.ask(prompt, model="openai/o3", base_url=None)` - 具有网页搜索工具的 AI 助手 - `searxng.get_available_engines()` - 获取引擎信息 - `searxng.get_categories()` - 获取搜索类别 - `searxng.SearXNGClient(**defaults)` - 具有可重用设置的客户端类 所有函数都有异步变体（`search_async`、`fetch_url_async`、`ask_async` 等）。 ## 许可证 此 CLI 工具使用 SearXNG，它根据 AGPL-3.0 许可。有关完整的许可证详细信息，请参阅主存储库。