DDGS | 杜克斯分布式全球搜索

一个元搜索引擎库，可聚合来自不同网络搜索服务的结果。

目录

• 安装
• CLI 版本
• API 服务器
• MCP 服务器
• 引擎
• DDGS 类
• 1. text()
• 2. images()
• 3. videos()
• 4. news()
• 5. books()
• 6. extract()
• 免责声明

---

安装

pip install -U ddgs       # 基础安装
pip install -U ddgs[api]  # API 服务器 (FastAPI)
pip install -U ddgs[mcp]  # MCP 服务器 (stdio)

CLI 版本

ddgs --help

返回顶部

---

API 服务器

• 安装

pip install -U ddgs[api]

• CLI

ddgs api              # 在前台启动服务器
ddgs api -d           # 以分离模式（后台）启动
ddgs api -s           # 停止分离模式的服务器
ddgs api --host 127.0.0.1 --port 9000  # 自定义主机/端口
ddgs api -pr socks5h://127.0.0.1:9150  # 使用代理

• Docker Compose

git clone https://github.com/deedy5/ddgs && cd ddgs
docker-compose up --build

• Bash 脚本

git clone https://github.com/deedy5/ddgs && cd ddgs
chmod +x start_api.sh
./start_api.sh

端点

端点	方法	描述
/search/text	GET, POST	文本搜索
/search/images	GET, POST	图片搜索
/search/news	GET, POST	新闻搜索
/search/videos	GET, POST	视频搜索
/search/books	GET, POST	书籍搜索
/extract	GET, POST	从 URL 提取内容
/health	GET	健康检查
/docs	GET	Swagger UI
/redoc	GET	ReDoc 文档

返回顶部

---

MCP 服务器

• 安装

pip install -U ddgs[mcp]

• CLI

ddgs mcp    # 启动 MCP 服务器（stdio 传输）
ddgs mcp -pr socks5h://127.0.0.1:9150  # 使用代理

可用工具

工具	描述
search_text	网页文本搜索
search_images	图片搜索
search_news	新闻搜索
search_videos	视频搜索
search_books	书籍搜索
extract_content	从 URL 提取内容

客户端配置

对于 Cursor 或 Claude Desktop 等 MCP 客户端：

{
  "mcpServers": {
    "ddgs": {
      "command": "ddgs",
      "args": ["mcp"]
    }
  }
}

返回顶部

---

引擎

DDGS 函数	可用后端
text()	bing, brave, duckduckgo, google, grokipedia, mojeek, yandex, yahoo, wikipedia
images()	bing, duckduckgo
videos()	duckduckgo
news()	bing, duckduckgo, yahoo
books()	annasarchive

返回顶部

DDGS 类

DDGS 类采用懒加载方式。

class DDGS:
    """杜克斯分布式全球搜索。一个元搜索引擎库，可聚合来自不同网络搜索服务的结果。

    参数:
        proxy (str, 可选): HTTP 客户端使用的代理，支持 http/https/socks5 协议。
            示例: "http://user:pass@example.com:3128"。默认为 None。
        timeout (int, 可选): HTTP 客户端的超时时间。默认为 5 秒。
        verify: (bool 或 str): True 表示验证，False 表示跳过，或指定 PEM 文件路径。默认为 True。
    """

以下是初始化 DDGS 类的示例。

from ddgs import DDGS

results = DDGS().text("python 编程", max_results=5)
print(results)

返回顶部

1. text()

def text(
    query: str,
    region: str = "us-en",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
) -> list[dict[str, str]]:
    """DDGS 文本元搜索引擎。

    参数:
        query: 文本搜索查询。
        region: us-en、uk-en、ru-ru 等。默认为 us-en。
        safesearch: on、moderate、off。默认为 "moderate"。
        timelimit: d、w、m、y。默认为 None。
        max_results: 最大结果数。默认为 10。
        page: 结果页码。默认为 1。
        backend: 单个或逗号分隔的后端列表。默认为 "auto"。

    返回:
        包含搜索结果的字典列表。
    """

示例

results = DDGS().text('live free or die', region='us-en', safesearch='off', timelimit='y', page=1, backend="auto")
# 搜索 PDF 文件
results = DDGS().text('russia filetype:pdf', region='us-en', safesearch='off', timelimit='y', page=1, backend="auto")
print(results)
[
    {
        "title": "新闻、体育、名人与八卦 | 太阳报",
        "href": "https://www.thesun.co.uk/",
        "body": "获取太阳报最新的新闻、独家报道、体育、名人、娱乐、政治、商业和生活方式资讯",
    }, ...
]

返回顶部

2. images()

def images(
    query: str,
    region: str = "us-en",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
    size: str | None = None,
    color: str | None = None,
    type_image: str | None = None,
    layout: str | None = None,
    license_image: str | None = None,
) -> list[dict[str, str]]:
    """DDGS 图片元搜索引擎。

    参数:
        query: 图片搜索关键词。
        region: 美国-英语、英国-英语、俄罗斯-俄语等。默认为美国-英语。
        safesearch: 开启、中等、关闭。默认为“中等”。
        timelimit: d（天）、w（周）、m（月）、y（年）。默认为 None。
        max_results: 最大结果数。默认为 10。
        page: 结果页码。默认为 1。
        backend: 单个或以逗号分隔的搜索引擎。默认为“auto”。
        size: 小、中、大、壁纸。默认为 None。
        color: 彩色、单色、红色、橙色、黄色、绿色、蓝色、紫色、粉色、棕色、黑色、灰色、青绿色、白色。默认为 None。
        type_image: 照片、剪贴画、GIF、透明、线稿。默认为 None。
        layout: 正方形、长图、宽图。默认为 None。
        license_image: 任意（所有知识共享）、公共领域、可分享、可商业使用、可修改、可商业修改。默认为 None。

    返回:
        包含图片搜索结果的字典列表。
    """

示例

results = DDGS().images(
    query="butterfly",
    region="us-en",
    safesearch="off",
    timelimit="m",
    page=1,
    backend="auto",
    size=None,
    color="Monochrome",
    type_image=None,
    layout=None,
    license_image=None,
)
print(images)
[
    {
        "title": "文件：太阳由美国宇航局太阳动力学天文台的大气成像组件拍摄……",
        "image": "https://upload.wikimedia.org/wikipedia/commons/b/b4/The_Sun_by_the_Atmospheric_Imaging_Assembly_of_NASA's_Solar_Dynamics_Observatory_-_20100819.jpg",
        "thumbnail": "https://tse4.mm.bing.net/th?id=OIP.lNgpqGl16U0ft3rS8TdFcgEsEe&pid=Api",
        "url": "https://en.wikipedia.org/wiki/File:The_Sun_by_the_Atmospheric_Imaging_Assembly_of_NASA's_Solar_Dynamics_Observatory_-_20100819.jpg",
        "height": 3860,
        "width": 4044,
        "source": "Bing",
    }, ...
]

返回顶部

3. videos()

def videos(
    query: str,
    region: str = "us-en",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
    resolution: str | None = None,
    duration: str | None = None,
    license_videos: str | None = None,
) -> list[dict[str, str]]:
    """DDGS 视频元搜索引擎。

    参数:
        query: 视频搜索关键词。
        region: 美国-英语、英国-英语、俄罗斯-俄语等。默认为美国-英语。
        safesearch: 开启、中等、关闭。默认为“中等”。
        timelimit: d（天）、w（周）、m（月）。默认为 None。
        max_results: 最大结果数。默认为 10。
        page: 结果页码。默认为 1。
        backend: 单个或以逗号分隔的搜索引擎。默认为“auto”。
        resolution: 高清、标准。默认为 None。
        duration: 短、中、长。默认为 None。
        license_videos: 知识共享、YouTube。默认为 None。

    返回:
        包含视频搜索结果的字典列表。
    """

示例

results = DDGS().videos(
    query="cars",
    region="us-en",
    safesearch="off",
    timelimit="w",
    page=1,
    backend="auto",
    resolution="high",
    duration="medium",
)
print(results)
[
    {
        "content": "https://www.youtube.com/watch?v=6901-C73P3g",
        "description": "观看热门泰米尔连续剧《Meena》在Sun TV播出的最佳片段。在Sun NXT应用上，您可以在电视播出后立即观看所有Sun TV连续剧。*仅限印度用户免费下载：Android - http://bit.ly/SunNxtAdroid iOS：印度 - http://bit.ly/sunNXT 在网页上观看 - https://www.sunnxt.com/ 两位亲密的朋友，Chidambaram ...",
        "duration": "8:22",
        "embed_html": '<iframe width="1280" height="720" src="https://www.youtube.com/embed/6901-C73P3g?autoplay=1" frameborder="0" allowfullscreen></iframe>',
        "embed_url": "https://www.youtube.com/embed/6901-C73P3g?autoplay=1",
        "image_token": "6c070b5f0e24e5972e360d02ddeb69856202f97718ea6c5d5710e4e472310fa3",
        "images": {
            "large": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
            "medium": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
            "motion": "",
            "small": "https://tse4.mm.bing.net/th?id=OVF.JWBFKm1u%2fHd%2bz2e1GitsQw&pid=Api",
        },
        "provider": "Bing",
        "published": "2024-07-03T05:30:03.0000000",
        "publisher": "YouTube",
        "statistics": {"viewCount": 29059},
        "title": "Meena - 最佳片段 | 2024年7月2日 | 泰米尔连续剧 | Sun TV",
        "uploader": "Sun TV",
    }, ...
]

返回顶部

4. news()

def news(
    query: str,
    region: str = "us-en",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
) -> list[dict[str, str]]:
    """DDGS 新闻元搜索引擎。

    参数:
        query: 新闻搜索关键词。
        region: 美国-英语、英国-英语、俄罗斯-俄语等。默认为美国-英语。
        safesearch: 开启、中等、关闭。默认为“中等”。
        timelimit: d（天）、w（周）、m（月）。默认为 None。
        max_results: 最大结果数。默认为 10。
        page: 结果页码。默认为 1。
        backend: 单个或以逗号分隔的搜索引擎。默认为“auto”。

    返回:
        包含新闻搜索结果的字典列表。
    """

示例

results = DDGS().news(query="sun", region="us-en", safesearch="off", timelimit="m", page=1, backend="auto")
print(results)
[
    {
        "date": "2024-07-03T16:25:22+00:00",
        "title": "默多克旗下的《太阳报》在英国大选前支持斯塔默领导的工党",
        "body": "鲁珀特·默多克旗下的《太阳报》宣布支持基尔·斯塔默及其反对党工党赢得英国大选，这一戏剧性的举动标志着英国媒体格局的重大转变，也反映了该国政治版图的变化。",
        "url": "https://www.msn.com/en-us/money/other/murdoch-s-sun-endorses-starmer-s-labour-day-before-uk-vote/ar-BB1plQwl",
        "image": "https://img-s-msn-com.akamaized.net/tenant/amp/entityid/BB1plZil.img?w=2000&h=1333&m=4&q=79",
        "source": "彭博社在MSN.com上",
    }, ...
]

返回顶部

5. books()

def books(
    query: str,
    max_results: int | None = 10,
    page: int = 1,
    backend: str = "auto",
) -> list[dict[str, str]]:
    """DDGS 图书元搜索引擎。

    参数:
        query: 图书搜索查询。
        max_results: 最大结果数。默认为10。
        page: 结果页码。默认为1。
        backend: 单个或逗号分隔的后端。默认为“auto”。

    返回:
        包含图书搜索结果的字典列表。
    """

示例

results = DDGS().books(query="海狼 杰克·伦敦", page=1, backend="auto")
print(results)
[
    {
        'title': '海狼',
        'author': '杰克·伦敦',
        'publisher': 'DigiCat, 2022',
        'info': '英语 [en], .epub, 🚀/zlib, 0.5MB, 📗 书籍（未知）',
        'url': 'https://annas-archive.li/md5/574f6556f1df6717de4044e36c7c2782',
        'thumbnail': 'https://s3proxy.cdn-zlib.sk//covers299/collections/userbooks/da4954486be7c2b2b9f70b2aa5bcf01292de3ea510b5656f892821950ded9ada.jpg',
    }, ...
]

返回顶部

6. extract()

获取指定 URL 的内容，并以多种格式提取。

def extract(
    url: str,
    fmt: str = "text_markdown",
) -> dict[str, str | bytes]:
    """获取 URL 并提取其内容。

    参数:
        url: 要获取并提取内容的 URL。
        fmt: 输出格式：
            "text_markdown"（HTML→Markdown，保留链接/标题/列表），
            "text_plain"（HTML→纯文本），
            "text_rich"（HTML→带标题/列表的富文本），
            "text"（原始 HTML），
            "content"（原始字节数据）。

    返回:
        包含 'url' 和 'content' 键的字典。
    """

示例

# Markdown（默认） - 保留链接、标题、列表
result = DDGS().extract("https://example.com")
print(result)
{"url": "https://example.com", "content": "# 示例域名\n\n此域名用于..."}

# 纯文本
result = DDGS().extract("https://example.com", fmt="text_plain")

# 富文本（标题/列表，无链接 URL）
result = DDGS().extract("https://example.com", fmt="text_rich")

# 原始 HTML
result = DDGS().extract("https://example.com", fmt="text")

# 原始字节数据
result = DDGS().extract("https://example.com", fmt="content")

命令行界面

ddgs extract -u https://example.com
ddgs extract -u https://example.com -f text_plain
ddgs extract -u https://example.com -f content -o output.json

返回顶部

免责声明

本库仅用于教育目的。

DDGS 快速上手指南

DDGS (Dux Distributed Global Search) 是一个聚合了多种网络搜索服务结果的元搜索引擎库，支持文本、图片、视频、新闻和书籍搜索，并提供 CLI、API Server 和 MCP Server 等多种使用方式。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：>= 3.10
• 前置依赖：无特殊系统级依赖，需确保 pip 可用。

提示：国内用户建议使用国内镜像源加速安装（如清华源、阿里源）。

安装步骤

1. 基础安装（Python 库）

仅用于在 Python 代码中调用：

pip install -U ddgs -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装 API 服务器

如需启动 HTTP API 服务（基于 FastAPI）：

pip install -U "ddgs[api]" -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 安装 MCP 服务器

如需对接 Cursor、Claude Desktop 等 MCP 客户端：

pip install -U "ddgs[mcp]" -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

方式一：Python 代码调用（推荐）

这是最直接的用法，支持文本、图片、视频等多种搜索类型。

示例：执行文本搜索

from ddgs import DDGS

# 初始化并执行搜索
# query: 搜索关键词
# max_results: 最大返回结果数
# backend: 指定后端引擎 (如 'google', 'bing', 'duckduckgo')，默认为 'auto' 自动选择
results = DDGS().text("python programming", max_results=5, backend="auto")

# 打印结果
for item in results:
    print(f"标题：{item['title']}")
    print(f"链接：{item['href']}")
    print(f"摘要：{item['body']}\n")

其他搜索类型示例：

# 图片搜索
images = DDGS().images("butterfly", max_results=3)

# 新闻搜索
news = DDGS().news("AI technology", timelimit="w") # 限制为一周内

# 视频搜索
videos = DDGS().videos("tutorial", resolution="high")

方式二：命令行工具 (CLI)

安装后可直接在终端使用：

# 查看帮助
ddgs --help

# 执行文本搜索 (示例)
ddgs text "python programming" --max-results 5

方式三：启动 API 服务

安装 ddgs[api] 后，可启动本地搜索 API 服务：

# 前台启动
ddgs api

# 自定义端口启动
ddgs api --host 127.0.0.1 --port 9000

# 启动后可访问 http://127.0.0.1:9000/docs 查看 Swagger 文档

方式四：配置 MCP 服务

适用于 AI 编辑器（如 Cursor）集成。在客户端配置文件中添加：

{
  "mcpServers": {
    "ddgs": {
      "command": "ddgs",
      "args": ["mcp"]
    }
  }
}

配置完成后，AI 助手即可直接调用 search_text, search_images 等工具进行联网搜索。