README

Extractor：为 Laravel 提供的 AI 数据提取库。

使用 Laravel 中的 OpenAI，轻松从各种来源提取结构化数据，包括图片、PDF 和电子邮件。

特性

围绕 OpenAI Chat 和 Completion 端点的方便包装。
支持多种输入格式，如纯文本、PDF、RTF、图片、Word 文档和网页内容。
包括灵活的字段提取器，可以提取任意数据，无需编写自定义逻辑。
可以返回常规数组或 Spatie/data 对象。
与 Textract 集成以实现 OCR 功能。
使用来自最新 GPT-3.5 和 GPT-4 模型的 JSON 模式。

示例

示例代码

<?php

use HelgeSverre\Extractor\Facades\Extractor;
use HelgeSverre\Extractor\Facades\Text;
use Illuminate\Support\Facades\Storage;

$image = Storage::get("restaurant_menu.png")

// Extract text from images
$textFromImage = Text::textract($image);

// Extract structured data from plain text
$menu = Extractor::fields($textFromImage,
    fields: [
        'restaurantName',
        'phoneNumber',
        'dishes' => [
            'name' => 'name of the dish',
            'description' => 'description of the dish',
            'price' => 'price of the dish as a number',
        ],
    ],
    model: "gpt-3.5-turbo-1106",
    maxTokens: 4000,
);

安装

使用 composer 安装包

composer require helgesverre/extractor

发布配置文件

php artisan vendor:publish --tag="extractor-config"

您可以在配置文件中找到所有配置选项。

由于此包依赖于 OpenAI Laravel 包，您还需要发布他们的配置并在您的 .env 文件中添加 OPENAI_API_KEY

php artisan vendor:publish --provider="OpenAI\Laravel\ServiceProvider"

OPENAI_API_KEY="your-key-here"

# Optional: Set request timeout (default: 30s).
OPENAI_REQUEST_TIMEOUT=60

使用方法

从文档中提取纯文本

use HelgeSverre\Extractor\Facades\Text;

$textPlainText = Text::text(file_get_contents('./data.txt'));
$textPdf = Text::pdf(file_get_contents('./data.pdf'));
$textImageOcr = Text::textract(file_get_contents('./data.jpg'));
$textPdfOcr = Text::textractUsingS3Upload(file_get_contents('./data.pdf'));
$textWord = Text::word(file_get_contents('./data.doc'));
$textWeb = Text::web('https://example.com');
$textHtml = Text::html(file_get_contents('./data.html'));

提取结构化数据

Extractor 包包含一组预构建的提取器，旨在简化从各种类型文本中提取结构化数据的操作。每个提取器都针对特定的数据格式进行了优化，使得处理不同类型信息变得容易。以下是包含的提取器的列表，包括简要描述和每个提取器的便捷简写方法

这些提取器是现成的，提供了一种方便的方法，可以从文本中提取特定类型的结构化数据。您可以使用简写方法轻松访问每个提取器的功能。

使用字段提取器

如果不需要太多自定义逻辑或验证，只需从一段文本中提取一些结构化数据，字段提取器就非常棒。

以下是从简历中提取信息的示例，请注意，提供描述以引导 AI 模型是支持的，以及嵌套项（这对于子项列表很有用，如工作历史、行项目、产品评论等）

$sample = Text::pdf(file_get_contents(__DIR__.'/../samples/helge-cv.pdf'));

$data = Extractor::fields($sample,
    fields: [
        'name' => 'the name of the candidate',
        'email',
        'certifications' => 'list of certifications, if any',
        'workHistory' => [
            'companyName',
            'from' => 'Y-m-d if available, Year only if not, null if missing',
            'to' => 'Y-m-d if available, Year only if not, null if missing',
            'text',
        ],
    ],
    model: Engine::GPT_3_TURBO_1106,
);

使用 GPT-4-Vision 与 Extractor 集成

注意：此功能仍在进行中。

Extractor 包还与 OpenAI 的新 Vision API 集成，利用强大的 gpt-4-vision-preview 模型从图像中提取结构化数据。此功能使您能够轻松分析和理解视觉内容，无论是从图像中读取文本、从图表中提取数据，还是理解复杂的视觉场景。

如何使用 ImageContent 与 OpenAI 的 Vision API

要使用 Extractor 中的 Vision 功能，您需要提供图像作为输入。这可以通过几种不同的方式完成

使用文件路径：从文件路径加载图像。
使用原始图像数据：使用图像的原始数据，例如，来自上传的文件。
使用图像URL：直接从URL加载图像。

以下是您可以使用每种方法的步骤

使用文件路径

use HelgeSverre\Extractor\Text\ImageContent;

$imagePath = __DIR__ . '/../samples/sample-image.jpg';
$imageContent = ImageContent::file($imagePath);

使用原始图像数据

use HelgeSverre\Extractor\Text\ImageContent;

$rawImageData = file_get_contents(__DIR__ . '/../samples/sample-image.jpg');
$imageContent = ImageContent::raw($rawImageData);

使用图像URL

use HelgeSverre\Extractor\Text\ImageContent;

$imageUrl = 'https://example.com/sample-image.jpg';
$imageContent = ImageContent::url($imageUrl);

使用OpenAI的Vision API从图像中提取数据

在准备完您的 ImageContent 对象后，您可以将它传递给 Extractor::fields 方法，使用OpenAI的Vision API提取结构化数据。例如

use HelgeSverre\Extractor\Facades\Extractor;
use HelgeSverre\Extractor\Text\ImageContent;

$imageContent = ImageContent::file(__DIR__ . '/../samples/product-catalog.jpg');

$data = Extractor::fields(
    $imageContent,
    fields: [
        'productName',
        'price',
        'description',
    ],
    model: Engine::GPT_4_VISION,
);

创建自定义提取器

Extractor中的自定义提取器允许进行定制数据提取以满足特定需求。以下是创建和使用自定义提取器的示例，以职位发布提取器为例。

实现自定义提取器

通过扩展 Extractor 类创建一个新的自定义提取器类。在这个例子中，我们将创建一个 JobPostingExtractor 来从职位发布中提取关键信息。

<?php

namespace App\Extractors;

use HelgeSverre\Extractor\Extraction\Extractor;use HelgeSverre\Extractor\Text\TextContent;

class JobPostingExtractor extends Extractor
{
    public function prompt(string|TextContent $input): string
    {
        $outputKey = $this->expectedOutputKey();

        return "Extract the following fields from the job posting below:"
            . "\n- jobTitle: The title or designation of the job."
            . "\n- companyName: The name of the company or organization posting the job."
            . "\n- location: The geographical location or workplace where the job is based."
            . "\n- jobType: The nature of employment (e.g., Full-time, Part-time, Contract)."
            . "\n- description: A brief summary or detailed description of the job."
            . "\n- applicationDeadline: The closing date for applications, if specified."
            . "\n\nThe output should be a JSON object under the key '{$outputKey}'."
            . "\n\nINPUT STARTS HERE\n\n$input\n\nOUTPUT IN JSON:\n";
    }

    public function expectedOutputKey(): string
    {
        return 'extractedData';
    }
}

注意：建议添加一个指令说明哪个 $outputKey 键来嵌套数据，因为OpenAI的JsonMode响应默认希望将所有内容放在根键下。通过覆盖 expectedOutputKey() 方法，它将告诉基类提取数据的哪个键。

注册自定义提取器

定义完您的自定义提取器后，使用 extend 方法将其注册到主Extractor类中。

use HelgeSverre\Extractor\Extractor;

Extractor::extend("job-posting", fn() => new JobPostingExtractor());

使用自定义提取器

一旦注册，您就可以像使用内置提取器一样使用自定义提取器。以下是使用 JobPostingExtractor 的示例。

use HelgeSverre\Extractor\Facades\Text;
use HelgeSverre\Extractor\Extractor;

$jobPostingContent = Text::web("https://www.finn.no/job/fulltime/ad.html?finnkode=329443482");

$extractedData = Extractor::extract('job-posting', $jobPostingContent);
// Or you can specify the class-string instead
// ex: Extractor::extract(JobPostingExtractor::class, $jobPostingContent);

// $extractedData now contains structured information from the job posting

使用 JobPostingExtractor，您可以高效地解析和提取职位发布中的关键信息，并以易于管理和在Laravel应用程序中使用的方式对其进行结构化。

向职位发布提取器添加验证

为确保提取数据的完整性，您可以为职位发布提取器添加验证规则。这通过使用 HasValidation 特性并在 rules 方法中定义验证规则来完成。

<?php

namespace App\Extractors;

use HelgeSverre\Extractor\Extraction\Concerns\HasValidation;
use HelgeSverre\Extractor\Extraction\Extractor;

class JobPostingExtractor extends Extractor
{
    use HasValidation;

    public function rules(): array
    {
        return [
            'jobTitle' => ['required', 'string'],
            'companyName' => ['required', 'string'],
            'location' => ['required', 'string'],
            'jobType' => ['required', 'string'],
            'salary' => ['required', 'numeric'],
            'description' => ['required', 'string'],
            'applicationDeadline' => ['required', 'date']
        ];
    }
}

这将确保职位发布数据中的每个键字段都符合指定的标准，从而增强数据提取的可靠性。

将数据提取到DTO中

Extractor可以与spatie/data集成，将提取的数据转换为选择的Data Transfer Object (DTO)。为此，将 HasDto 特性添加到您的提取器中，并在 dataClass 方法中指定DTO类。

<?php

namespace App\Extractors;

use DateTime;
use App\Extractors\JobPostingDto;
use HelgeSverre\Extractor\Extraction\Concerns\HasDto;
use HelgeSverre\Extractor\Extraction\Extractor;
use Spatie\LaravelData\Data;

class JobPostingDto extends Data
{
    public function __construct(
        public string $jobTitle,
        public string $companyName,
        public string $location,
        public string $jobType,
        public int|float $salary,
        public string $description,
        public DateTime $applicationDeadline
    ) {
    }
}

class JobPostingExtractor extends Extractor
{
    use HasDto;

    public function dataClass(): string
    {
        return JobPostingDto::class;
    }

    public function isCollection(): bool
    {
        return false; 
    }
}

使用AWS Textract进行OCR配置

要使用AWS Textract从大图像和多页PDF中提取文本，该包需要将文件上传到S3，并将S3对象位置传递给textract服务。

因此，您需要在 config/extractor.php 文件中配置您的AWS凭证，如下所示

TEXTRACT_KEY="your-aws-access-key"
TEXTRACT_SECRET="your-aws-security"
TEXTRACT_REGION="your-textract-region"

# Can be omitted
TEXTRACT_VERSION="2018-06-27"

您还需要配置一个单独的textract磁盘，其中将存储文件。打开您的 config/filesystems.php 配置文件并添加以下内容

'textract' => [
    'driver' => 's3',
    'key' => env('TEXTRACT_KEY'),
    'secret' => env('TEXTRACT_SECRET'),
    'region' => env('TEXTRACT_REGION'),
    'bucket' => env('TEXTRACT_BUCKET'),
],

请确保 config/extractor.php 中的 textract_disk 设置与 filesystems.php 配置中的磁盘名称相同，您可以使用 .env 值 TEXTRACT_DISK 进行更改。

return [
    "textract_disk" => env("TEXTRACT_DISK")
];

.env

TEXTRACT_DISK="uploads"

使用textract处理后删除文件

使用S3生命周期规则

您可以在S3存储桶上配置生命周期规则以在一段时间后删除文件，有关更多信息，请参阅AWS文档

https://repost.aws/knowledge-center/s3-empty-bucket-lifecycle-rule

使用 `cleanupFileUsing` 钩子

默认情况下，该包不会删除已上传到textract S3桶的文件。如果您想删除这些文件，您可以通过实现 TextractUsingS3Upload::cleanupFileUsing(Closure) 钩子来实现。

// Delete the file from the S3 bucket
TextractUsingS3Upload::cleanupFileUsing(function (string $filePath) {
    Storage::disk('textract')->delete($filePath);
}

注意

Textract并非在所有地区都可用

Q: 亚马逊Textract在哪些AWS区域可用？亚马逊Textract目前在美国东部（北部弗吉尼亚）、美国东部（俄亥俄）、美国西部（俄勒冈）、美国西部（北加利福尼亚）、AWS GovCloud（美国西部）、AWS GovCloud（美国东部）、加拿大（中部）、欧洲（爱尔兰）、欧洲（伦敦）、欧洲（法兰克福）、欧洲（巴黎）、亚太（新加坡）、亚太（悉尼）、亚太（首尔）和亚太（孟买）区域可用。

参阅：https://aws.amazon.com/textract/faqs/

所有参数及其功能

$input（TextContent|string）

需要处理的输入文本或数据。它接受一个TextContent对象或字符串。

$model（Model）

此参数指定用于提取过程的OpenAI模型。

它接受一个string值。不同的模型具有不同的速度/精度特征和用例，为了方便起见，大多数接受的模型都作为常量在Engine类中提供。

可用模型

$maxTokens（int）

模型将处理的令牌的最大数量。默认值是2000，对于非常长的文本可能需要调整此值。2000通常足够。

$temperature（float）

控制模型输出的随机性/创造力。

更高的值（例如，0.8）会使输出更加随机，这在当前上下文中通常是不希望的。建议的值是0.1或0.2；超过0.5的值往往不太有用。默认值是0.1。

许可证

此软件包在MIT许可证下授权。有关更多详细信息，请参阅许可证文件。

helgesverre / extractor

维护者

详细信息

README

Extractor：为 Laravel 提供的 AI 数据提取库。

特性

示例

安装

使用方法

从文档中提取纯文本

提取结构化数据

使用字段提取器

使用 GPT-4-Vision 与 Extractor 集成

如何使用 ImageContent 与 OpenAI 的 Vision API

使用文件路径

使用原始图像数据

使用图像URL

使用OpenAI的Vision API从图像中提取数据

创建自定义提取器

实现自定义提取器

注册自定义提取器

使用自定义提取器

向职位发布提取器添加验证

将数据提取到DTO中

使用AWS Textract进行OCR配置

使用textract处理后删除文件

使用S3生命周期规则

使用 `cleanupFileUsing` 钩子

所有参数及其功能

许可证

helgesverre / extractor

维护者

详细信息

README

Extractor：为 Laravel 提供的 AI 数据提取库。

特性

示例

安装

使用方法

从文档中提取纯文本

提取结构化数据

使用字段提取器

使用 GPT-4-Vision 与 Extractor 集成

如何使用 ImageContent 与 OpenAI 的 Vision API

使用文件路径

使用原始图像数据

使用图像URL

使用OpenAI的Vision API从图像中提取数据

创建自定义提取器

实现自定义提取器

注册自定义提取器

使用自定义提取器

向职位发布提取器添加验证

将数据提取到DTO中

使用AWS Textract进行OCR配置

使用textract处理后删除文件

使用S3生命周期规则

使用 cleanupFileUsing 钩子

所有参数及其功能

许可证

使用 `cleanupFileUsing` 钩子