Source code for langchain_community.utilities.google_search

"""调用谷歌搜索的工具。"""

from typing import Any, Dict, List, Optional

from langchain_core._api.deprecation import deprecated
from langchain_core.pydantic_v1 import BaseModel, Extra, root_validator
from langchain_core.utils import get_from_dict_or_env


@deprecated(
    since="0.0.33",
    removal="0.3.0",
    alternative_import="langchain_google_community.GoogleSearchAPIWrapper",
)
class GoogleSearchAPIWrapper(BaseModel):
    """包装了Google搜索API。

    改编自：从https://stackoverflow.com/questions/
    37083058/ 改编的指令

    待办事项：使用文档
    1. 安装google-api-python-client
    - 如果您还没有Google账号，请注册。
    - 如果您从未创建过Google APIs控制台项目，请阅读管理项目页面并在Google API控制台中创建项目。
    - 使用pip install google-api-python-client安装库

    2. 启用自定义搜索API
    - 转到Cloud Console中的API和服务→仪表板面板。
    - 点击启用API和服务。
    - 搜索Custom Search API并点击它。
    - 点击启用。
    URL：https://console.cloud.google.com/apis/library/customsearch.googleapis
    .com

    3. 创建API密钥：
    - 转到Cloud Console中的API和服务 → 凭据面板。
    - 选择创建凭据，然后从下拉菜单中选择API密钥。
    - API密钥创建对话框显示您新创建的密钥。
    - 您现在有一个API_KEY

    或者，您可以在此处生成API密钥：
    https://developers.google.com/custom-search/docs/paid_element#api_key

    4. 设置自定义搜索引擎，以便搜索整个网络
    - 在此处创建自定义搜索引擎：https://programmablesearchengine.google.com/。
    - 在“搜索内容”中选择“搜索整个网络”选项。
    创建搜索引擎后，您可以单击它并在概述页面上找到“搜索引擎ID”。"""

    search_engine: Any  #: :meta private:
    google_api_key: Optional[str] = None
    google_cse_id: Optional[str] = None
    k: int = 10
    siterestrict: bool = False

    class Config:
        """此pydantic对象的配置。"""

        extra = Extra.forbid

    def _google_search_results(self, search_term: str, **kwargs: Any) -> List[dict]:
        cse = self.search_engine.cse()
        if self.siterestrict:
            cse = cse.siterestrict()
        res = cse.list(q=search_term, cx=self.google_cse_id, **kwargs).execute()
        return res.get("items", [])

    @root_validator()
    def validate_environment(cls, values: Dict) -> Dict:
        """验证环境中是否存在API密钥和Python包。"""
        google_api_key = get_from_dict_or_env(
            values, "google_api_key", "GOOGLE_API_KEY"
        )
        values["google_api_key"] = google_api_key

        google_cse_id = get_from_dict_or_env(values, "google_cse_id", "GOOGLE_CSE_ID")
        values["google_cse_id"] = google_cse_id

        try:
            from googleapiclient.discovery import build

        except ImportError:
            raise ImportError(
                "google-api-python-client is not installed. "
                "Please install it with `pip install google-api-python-client"
                ">=2.100.0`"
            )

        service = build("customsearch", "v1", developerKey=google_api_key)
        values["search_engine"] = service

        return values

    def run(self, query: str) -> str:
        """通过GoogleSearch运行查询并解析结果。"""
        snippets = []
        results = self._google_search_results(query, num=self.k)
        if len(results) == 0:
            return "No good Google Search Result was found"
        for result in results:
            if "snippet" in result:
                snippets.append(result["snippet"])

        return " ".join(snippets)

    def results(
        self,
        query: str,
        num_results: int,
        search_params: Optional[Dict[str, str]] = None,
    ) -> List[Dict]:
        """运行查询通过GoogleSearch并返回元数据。

参数：
    query：要搜索的查询。
    num_results：要返回的结果数量。
    search_params：要传递的搜索参数。

返回：
    一个包含以下键的字典列表：
        snippet - 结果的描述。
        title - 结果的标题。
        link - 结果的链接。
"""
        metadata_results = []
        results = self._google_search_results(
            query, num=num_results, **(search_params or {})
        )
        if len(results) == 0:
            return [{"Result": "No good Google Search Result was found"}]
        for result in results:
            metadata_result = {
                "title": result["title"],
                "link": result["link"],
            }
            if "snippet" in result:
                metadata_result["snippet"] = result["snippet"]
            metadata_results.append(metadata_result)

        return metadata_results