从LAION-5B在线数据库高效获取指定类别图像的Python教程

本教程详细介绍了如何使用python从大型在线图像数据库laion-5b的k-nn服务中，根据指定类别高效地获取并下载图像。通过`requests`库发送api请求，解析json响应，并流式下载图片，避免了下载整个庞大数据集的困扰，特别适用于个人项目和资源有限的场景。

在处理图像相关的个人项目时，我们经常需要特定类别的图像数据。然而，诸如ImageNet或LAION-5B这样的大型在线数据库通常包含海量数据，直接下载整个数据集既耗时又占用大量存储空间。本教程将引导您使用Python，通过LAION的k-NN（最近邻）服务API，高效地从LAION-5B数据库中按需获取指定类别的图像，而无需下载整个数据集。

1. 理解LAION-5B与k-NN服务

LAION-5B是一个庞大的图像-文本对数据集，包含了数十亿张图片及其对应的文本描述。为了方便用户检索，LAION提供了k-NN服务，允许用户通过文本查询来查找相似的图像，并获取其URL。这个服务是本教程实现按类别获取图像的关键。

2. 准备工作

在开始之前，请确保您的Python环境中安装了以下库：

• requests: 用于发送HTTP请求。
• pandas: 用于处理API返回的JSON数据，方便提取图像URL。
• pathlib: 用于方便地处理文件路径。
• shutil: 用于高效地复制文件对象。

您可以通过以下命令安装它们：

立即学习“Python免费学习笔记（深入）”；

pip install requests pandas

pathlib和shutil通常是Python标准库的一部分，无需额外安装。

3. 实现步骤

以下是使用Python从LAION-5B获取指定类别图像的详细步骤。

3.1 初始化配置

首先，我们需要定义一些基本参数，包括图像保存目录、目标类别标签、LAION k-NN服务的URL以及请求头。

import pathlib
import shutil
import pandas as pd
import requests
from requests.exceptions import ConnectionError, RequestException

# 定义图像保存的根目录
IMAGE_DIR = pathlib.Path('downloaded_images')
# 定义要获取的图像类别标签
LABEL = 'cat'  # 您可以修改为任何感兴趣的类别，例如 'dog', 'car', 'flower' 等

# LAION k-NN 服务的API端点
LAION_KNN_URL = 'https://knn.laion.ai/knn-service'
# HTTP请求头，模拟浏览器访问，避免被服务器拒绝
HEADERS = {
    'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64; rv:120.0) Gecko/20100101 Firefox/120.0',
}

说明：

LongCat AI

美团推出的AI对话问答工具

下载

• IMAGE_DIR: 指定所有下载图像的存储位置。
• LABEL: 这是您希望获取的图像类别。LAION的k-NN服务会根据这个文本查询来查找相关的图像。
• LAION_KNN_URL: LAION k-NN服务的官方API地址。
• HEADERS: 设置User-Agent可以帮助您的请求看起来更像是一个合法的浏览器请求，减少被服务器阻止的可能性。

3.2 构建API请求负载

LAION k-NN服务接受一个JSON格式的请求负载，其中包含查询参数。

# 构建API请求的负载
PAYLOAD = {
   'modality': 'image',        # 查询的模态为图像
   'num_images': 40,           # 希望获取的图像数量
   'indice_name': 'laion5B-L-14', # 指定LAION-5B中的索引名称，'laion5B-L-14'是一个常用的索引
}

# 将类别标签添加到负载中，使用Python 3.9+ 的字典合并操作符 `|`
# 对于旧版本Python，可以使用 PAYLOAD.copy() 或 PAYLOAD.update({'text': LABEL})
request_payload = PAYLOAD | {'text': LABEL}

说明：

• modality: 指定查询类型，这里是'image'。
• num_images: 您希望从API获取的图像URL数量。请注意，API可能有最大限制。
• indice_name: LAION-5B有多个子索引，'laion5B-L-14'是一个常用的、包含大量高质量图像的索引。
• text: 这是您的查询文本，即您想要获取的图像类别。

3.3 发送API请求并解析响应

使用requests.post方法向LAION k-NN服务发送POST请求，并处理返回的JSON数据。

try:
    # 发送POST请求
    response = requests.post(LAION_KNN_URL, json=request_payload, headers=HEADERS)
    response.raise_for_status() # 检查HTTP请求是否成功 (2xx 状态码)

    # 将JSON响应转换为Pandas DataFrame，方便处理
    df = pd.DataFrame(response.json())
    print(f"成功从LAION-5B获取到 {len(df)} 条图像记录。")

except RequestException as e:
    print(f"请求LAION k-NN服务时发生错误: {e}")
    df = pd.DataFrame() # 请求失败时，创建一个空的DataFrame

说明：

• requests.post(): 发送HTTP POST请求。json参数会自动将Python字典序列化为JSON格式的请求体。
• response.raise_for_status(): 这是一个非常有用的方法，如果HTTP响应状态码不是200-299，它会抛出一个HTTPError异常。
• pd.DataFrame(response.json()): 将API返回的JSON数据转换为Pandas DataFrame。JSON响应通常是一个包含图像信息的列表，每个元素是一个字典，其中包含url等字段。

3.4 下载图像

获取到图像URL列表后，我们需要遍历这些URL并下载图片到本地。

# 为当前类别创建存储目录
target_dir = IMAGE_DIR / LABEL
target_dir.mkdir(exist_ok=True, parents=True) # 如果目录不存在则创建，parents=True 确保创建所有父目录

if not df.empty:
    # 遍历DataFrame中的每个图像URL并下载
    for img_url in df['url']:
        try:
            # 使用 stream=True 进行流式下载，避免一次性加载大文件到内存
            img_response = requests.get(img_url, stream=True, headers=HEADERS, timeout=10) # 增加超时设置
            img_response.raise_for_status() # 检查图像下载请求是否成功

            # 从URL中提取文件名
            img_filename = pathlib.Path(img_url).name
            file_path = target_dir / img_filename

            # 将图像内容写入文件
            with open(file_path, 'wb') as fp:
                shutil.copyfileobj(img_response.raw, fp)
            # print(f"已下载: {img_filename}")

        except ConnectionError:
            print(f"下载 {img_url} 时连接错误，跳过。")
        except RequestException as e:
            print(f"下载 {img_url} 时发生请求错误: {e}")
        except Exception as e:
            print(f"下载 {img_url} 时发生未知错误: {e}")
else:
    print("没有获取到图像URL，无法进行下载。")

print(f"指定类别 '{LABEL}' 的图像已下载至目录: {target_dir}")

说明：

• target_dir.mkdir(exist_ok=True, parents=True): 创建用于存储当前类别图像的子目录。exist_ok=True表示如果目录已存在则不报错，parents=True表示如果父目录不存在也会一并创建。
• requests.get(img_url, stream=True): 这是下载大文件的最佳实践。stream=True表示不会立即下载整个响应体，而是允许您以块的形式读取。
• img_response.raise_for_status(): 检查图像下载请求是否成功。
• pathlib.Path(img_url).name: 从完整的URL中提取文件名（例如，https://example.com/image.jpg 会提取出 image.jpg）。
• shutil.copyfileobj(img_response.raw, fp): 将requests响应对象的原始套接字文件类对象（img_response.raw）直接复制到本地文件对象fp中。这种方式非常高效，尤其是在处理大文件时，因为它不会将整个文件加载到内存中。
• 错误处理：增加了ConnectionError和RequestException的捕获，以及一个通用的Exception捕获，以提高程序的健壮性。

4. 完整代码示例

将上述所有代码片段整合，即可得到一个完整的Python脚本：

import pathlib
import shutil
import pandas as pd
import requests
from requests.exceptions import ConnectionError, RequestException

def fetch_images_from_laion(label: str, num_images: int = 40, image_dir: str = 'downloaded_images'):
    """
    从LAION-5B的k-NN服务获取指定类别的图像。

    Args:
        label (str): 要获取的图像类别标签。
        num_images (int): 希望获取的图像数量。
        image_dir (str): 图像保存的根目录。
    """
    IMAGE_DIR = pathlib.Path(image_dir)
    LABEL = label

    LAION_KNN_URL = 'https://knn.laion.ai/knn-service'
    HEADERS = {
        'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64; rv:120.0) Gecko/20100101 Firefox/120.0',
    }
    PAYLOAD = {
       'modality': 'image',
       'num_images': num_images,
       'indice_name': 'laion5B-L-14',
    }

    request_payload = PAYLOAD | {'text': LABEL} # Python 3.9+ 字典合并

    df = pd.DataFrame() # 初始化为空DataFrame

    print(f"正在尝试从LAION-5B获取 '{LABEL}' 类别图像...")
    try:
        response = requests.post(LAION_KNN_URL, json=request_payload, headers=HEADERS, timeout=30)
        response.raise_for_status()
        df = pd.DataFrame(response.json())
        print(f"成功从LAION-5B获取到 {len(df)} 条图像记录。")

    except RequestException as e:
        print(f"请求LAION k-NN服务时发生错误: {e}")
        return

    target_dir = IMAGE_DIR / LABEL
    target_dir.mkdir(exist_ok=True, parents=True)

    if not df.empty:
        downloaded_count = 0
        for img_url in df['url']:
            try:
                img_response = requests.get(img_url, stream=True, headers=HEADERS, timeout=10)
                img_response.raise_for_status()

                img_filename = pathlib.Path(img_url).name
                file_path = target_dir / img_filename

                with open(file_path, 'wb') as fp:
                    shutil.copyfileobj(img_response.raw, fp)
                downloaded_count += 1
                # print(f"已下载: {img_filename}")

            except ConnectionError:
                print(f"下载 {img_url} 时连接错误，跳过。")
            except RequestException as e:
                print(f"下载 {img_url} 时发生请求错误: {e}")
            except Exception as e:
                print(f"下载 {img_url} 时发生未知错误: {e}")
        print(f"已成功下载 {downloaded_count} 张 '{LABEL}' 类别图像至目录: {target_dir}")
    else:
        print("没有获取到图像URL，无法进行下载。")

if __name__ == '__main__':
    # 示例用法
    fetch_images_from_laion(label='dog', num_images=50)
    fetch_images_from_laion(label='car', num_images=30, image_dir='my_project_images')
    fetch_images_from_laion(label='flower', num_images=20)

5. 注意事项与最佳实践

• API请求限制： LAION k-NN服务可能存在请求频率或数量限制。频繁或大量请求可能会导致IP被暂时封禁。请合理设置num_images和请求间隔。
• 错误处理： 代码中已包含try-except块来处理网络连接错误和HTTP请求错误。在实际应用中，您可以根据需要增加更详细的错误日志记录和重试机制。
• User-Agent： 使用User-Agent头是良好的网络请求习惯，可以模拟浏览器行为，降低被服务器拒绝的风险。
• indice_name： laion5B-L-14是一个常用的索引，但LAION可能提供其他索引。您可以查阅LAION的文档了解更多可用的索引。
• 超时设置： 在requests.post和requests.get中增加timeout参数是一个好习惯，可以防止程序因网络问题长时间阻塞。
• 数据伦理与版权： LAION-5B的数据来源于互联网，可能包含版权受保护的图像。在非商业或个人学习项目中使用时通常问题不大，但如果用于商业用途或公开发布，请务必注意图像的版权和使用许可。
• 内存管理： 使用stream=True和shutil.copyfileobj进行流式下载是处理大文件的最佳实践，可以有效避免内存溢出。

总结

通过本教程，您已经掌握了如何利用Python和LAION-5B的k-NN服务API，高效、按需地从大型在线数据库中获取指定类别的图像。这种方法避免了下载整个庞大数据集的困扰，极大地提高了图像数据获取的灵活性和效率，尤其适用于资源有限的个人项目和快速原型开发。请务必遵守API的使用规定和数据伦理，合理利用这些宝贵的图像资源。