LangSearch

⚠️ 安全性与凭证

必需的凭证：

• LANGSEARCH_API_KEY — 您的免费 LangSearch API 密钥（必填）

安全最佳实践：

1. 获取免费 API 密钥 — 在 langsearch.com/api-keys 注册
2. 保护您的 API 密钥 — 切勿将包含 LANGSEARCH_API_KEY 的 .env 文件提交至版本控制系统
3. 使用环境变量 — 将密钥存储在 .env 文件中，或通过 export LANGSEARCH_API_KEY="..." 设置
4. 监控用量 — 在 LangSearch 控制台中查看您的 API 调用情况
5. 代码审查 — 本工具仅调用官方 LangSearch API，所有通信均通过 HTTPS 发送至 api.langsearch.com

网络访问：

• 仅连接至：https://api.langsearch.com（官方 LangSearch API）
• 不进行外部数据收集或遥测上报
• 不向其他位置发送任何追踪或日志信息

概述

LangSearch 提供免费的网页搜索与语义重排序（semantic reranking）API。它融合了关键词搜索的精准性与基于向量的语义匹配能力，非常适合将最新网页信息集成至大语言模型（LLM）应用中，并用于构建 RAG 系统。

快速开始

前提条件

1. 前往 https://langsearch.com/api-keys 获取免费 API 密钥
2. 将您的 API 密钥设为环境变量：export LANGSEARCH_API_KEY="your-api-key"

基础网页搜索

使用 LangSearch 进行网页搜索的最简方式：

import requests
import json
import os

api_key = os.getenv("LANGSEARCH_API_KEY")
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

query = "latest AI developments 2025"
payload = {
    "query": query,
    "count": 5,
    "summary": True
}

response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json=payload
)

results = response.json()
print(json.dumps(results, indent=2))

或使用 cURL：

curl -X POST https://api.langsearch.com/v1/web-search \
  -H "Authorization: Bearer $LANGSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments 2025",
    "count": 5,
    "summary": true
  }'

网页搜索 API

网页搜索端点通过混合搜索（关键词 + 向量匹配）从数十亿网页文档中检索信息，并可选返回摘要内容。

端点

POST https://api.langsearch.com/v1/web-search

请求参数

响应结构

API 返回一个搜索结果数组，每个结果包含以下字段：

• title — 结果标题
• url — 结果 URL
• snippet — 页面中的文本片段
• summary — Markdown 格式摘要（仅当请求中设置 summary: true 时返回）
• score — 相关性得分

典型使用场景

实时信息检索
当您的 LLM 需要最新信息时：

# 搜索近期动态
response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json={
        "query": "Python 3.14 release notes",
        "count": 3,
        "summary": True,
        "freshness": "week"
    }
)

多查询研究
通过多个搜索构建上下文：

queries = [
    "climate change mitigation strategies",
    "renewable energy trends 2025",
    "carbon capture technology"
]

all_results = []
for query in queries:
    response = requests.post(
        "https://api.langsearch.com/v1/web-search",
        headers=headers,
        json={"query": query, "count": 5, "summary": True}
    )
    all_results.extend(response.json())

语义重排序 API

基于查询与文档之间的语义相关性对搜索结果进行重排序，从而提升搜索准确性。

端点

POST https://api.langsearch.com/v1/rerank

请求参数

示例：对网页搜索结果进行重排序

# 获取初始搜索结果
search_response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json={"query": "machine learning deployment best practices", "count": 10}
)

search_results = search_response.json()

# 准备用于重排序的文档
documents = [
    {"title": r.get("title", ""), "text": r.get("snippet", "")}
    for r in search_results
]

# 重排序以获得更高相关性
rerank_response = requests.post(
    "https://api.langsearch.com/v1/rerank",
    headers=headers,
    json={
        "query": "best practices for deploying ML models in production",
        "documents": documents,
        "top_n": 5
    }
)

reranked = rerank_response.json()

构建 RAG 应用

将网页搜索与大语言模型（LLM）上下文结合，实现更优的信息检索与内容生成：

def rag_query(user_question):
    # 步骤 1：搜索网页以获取相关信息
    search_response = requests.post(
        "https://api.langsearch.com/v1/web-search",
        headers=headers,
        json={
            "query": user_question,
            "count": 5,
            "summary": True
        }
    )

    search_results = search_response.json()

    # 步骤 2：提取摘要与 URL 作为上下文
    context = "\n".join([
        f"- {r['title']}: {r.get('summary', r.get('snippet', ''))}"
        for r in search_results
    ])

    # 步骤 3：与您的 LLM 配合使用
    # 此处应调用您的 LLM 并传入上下文
    rag_context = f"""
Based on recent web search results:

{context}

Answer the user's question: {user_question}
"""

    return rag_context, search_results

错误处理

常见 HTTP 状态码：

完整带错误处理的示例请参见 scripts/web_search_example.py。

资源

本技能包含若干示例资源目录，用于演示如何组织不同类型的打包资源：

scripts/

可直接运行的可执行代码（Python / Bash 等），用于完成特定操作。

其他技能中的示例：

• PDF 技能：fill_fillable_fields.py、extract_form_field_info.py — PDF 操作工具
• DOCX 技能：document.py、utilities.py — 文档处理 Python 模块

适用场景： Python 脚本、Shell 脚本，或其他用于自动化、数据处理或执行特定任务的可执行代码。

注意： 脚本可在不加载至上下文的情况下执行，但仍可能被 Claude 读取，用于补丁或环境调整。

references/

面向 Claude 的文档与参考材料，旨在加载至上下文中，辅助其推理与决策过程。

其他技能中的示例：

• 产品管理：communication.md、context_building.md — 详细工作流程指南
• BigQuery：API 参考文档与查询示例
• 金融领域：数据库 Schema 文档、公司政策文件

适用场景： 深度技术文档、API 参考、数据库 Schema、综合指南，或任何 Claude 在工作中需要引用的详细信息。

assets/

不用于加载至上下文，而是嵌入或用于 Claude 输出内容中的文件。

其他技能中的示例：

• 品牌规范：PowerPoint 模板文件（.pptx）、Logo 文件
• 前端构建器：HTML / React 项目脚手架目录
• 字体排印：字体文件（.ttf、.woff2）

适用场景： 模板、脚手架代码、文档模板、图片、图标、字体，或任何需复制到最终输出中的文件。

无需的目录可直接删除。 并非所有技能都需要全部三类资源。