データソースプラグイン

​

前提条件

• ステップ2：ナレッジパイプラインオーケストレーション
• Difyプラグイン開発：Hello Worldガイド

​

データソースプラグインの種類

• Webクローラー：Jina Reader、FireCrawl
• オンラインドキュメント：Notion、Confluence、GitHub
• オンラインドライブ：OneDrive、Google Drive、Box、AWS S3、Tencent COS

​

データソースプラグインの開発

​

データソースプラグインの作成

dify plugin init

​

データソースプラグインの構造

• manifest.yamlファイル：プラグインの基本情報を記述します。
• providerディレクトリ：プラグインプロバイダーの説明と認証実装コードを含みます。
• datasourcesディレクトリ：データソースからデータを取得するための説明とコアロジックを含みます。

├── _assets
│   └── icon.svg
├── datasources
│   ├── your_datasource.py
│   └── your_datasource.yaml
├── main.py
├── manifest.yaml
├── PRIVACY.md
├── provider
│   ├── your_datasource.py
│   └── your_datasource.yaml
├── README.md
└── requirements.txt

​

正しいバージョンとタグの設定

• manifest.yamlファイルで、最小サポートDifyバージョンを以下のように設定します：
  コピー

  minimum_dify_version: 1.9.0
  

• manifest.yamlファイルで、Dify Marketplaceのデータソースカテゴリにプラグインを表示するために以下のタグを追加します：
  コピー

  tags:
    - rag
  

• requirements.txtファイルで、データソースプラグイン開発に使用するプラグインSDKバージョンを以下のように設定します：
  コピー

  dify-plugin>=0.5.0,<0.6.0
  

​

データソースプロバイダーの追加

​

プロバイダーYAMLファイルの作成

# データソースプラグインのプロバイダータイプを指定：online_drive、online_document、またはwebsite_crawl
provider_type: online_drive # online_document, website_crawl

# データソースを指定
datasources:
  - datasources/PluginName.yaml

​

プロバイダーコードファイルの作成

• APIキー認証モードを使用する場合、データソースプラグインのプロバイダーコードファイルはツールプラグインと同一です。プロバイダークラスが継承する親クラスをDatasourceProviderに変更するだけです。
  コピー

  class YourDatasourceProvider(DatasourceProvider):
  
      def _validate_credentials(self, credentials: Mapping[str, Any]) -> None:
          try:
              """
              IMPLEMENT YOUR VALIDATION HERE
              """
          except Exception as e:
              raise ToolProviderCredentialValidationError(str(e))
  

• OAuth認証モードを使用する場合、データソースプラグインはツールプラグインとわずかに異なります。OAuthでアクセス権限を取得する際、データソースプラグインはフロントエンドに表示するユーザー名とアバターを同時に返すことができます。そのため、_oauth_get_credentialsと_oauth_refresh_credentialsはname、avatar_url、expires_at、credentialsを含むDatasourceOAuthCredentials型を返す必要があります。 DatasourceOAuthCredentialsクラスは以下のように定義されており、返す際に対応する型を設定する必要があります：
  コピー

  class DatasourceOAuthCredentials(BaseModel):
      name: str | None = Field(None, description="The name of the OAuth credential")
      avatar_url: str | None = Field(None, description="The avatar url of the OAuth")
      credentials: Mapping[str, Any] = Field(..., description="The credentials of the OAuth")
      expires_at: int | None = Field(
          default=-1,
          description="""The expiration timestamp (in seconds since Unix epoch, UTC) of the credentials.
          Set to -1 or None if the credentials do not expire.""",
      )
  

def _oauth_get_authorization_url(self, redirect_uri: str, system_credentials: Mapping[str, Any]) -> str:
"""
Generate the authorization URL for {{ .PluginName }} OAuth.
"""
try:
    """
    IMPLEMENT YOUR AUTHORIZATION URL GENERATION HERE
    """
except Exception as e:
    raise DatasourceOAuthError(str(e))
return ""

​

データソースの追加

​

Webクローラー

output_schema:
    type: object
    properties:
      source_url:
        type: string
        description: the source url of the website
      content:
        type: string
        description: the content from the website
      title:
        type: string
        description: the title of the website
      "description":
        type: string
        description: the description of the website

class YourDataSource(WebsiteCrawlDatasource):

    def _get_website_crawl(
        self, datasource_parameters: dict[str, Any]
    ) -> Generator[ToolInvokeMessage, None, None]:

        crawl_res = WebSiteInfo(web_info_list=[], status="", total=0, completed=0)
        crawl_res.status = "processing"
        yield self.create_crawl_message(crawl_res)
        
        ### your crawl logic
           ...
        crawl_res.status = "completed"
        crawl_res.web_info_list = [
            WebSiteInfoDetail(
                title="",
                source_url="",
                description="",
                content="",
            )
        ]
        crawl_res.total = 1
        crawl_res.completed = 1

        yield self.create_crawl_message(crawl_res)

​

オンラインドキュメント

output_schema:
    type: object
    properties:
      workspace_id:
        type: string
        description: workspace id
      page_id:
        type: string
        description: page id
      content:
        type: string
        description: page content

def _get_pages(self, datasource_parameters: dict[str, Any]) -> DatasourceGetPagesResponse:
    # your get pages logic
    response = requests.get(url, headers=headers, params=params, timeout=30)
    pages = []
    for item in  response.json().get("results", []):
        page = OnlineDocumentPage(
            page_name=item.get("title", ""),
            page_id=item.get("id", ""),
            type="page",  
            last_edited_time=item.get("version", {}).get("createdAt", ""),
            parent_id=item.get("parentId", ""),
            page_icon=None, 
        )
        pages.append(page)
    online_document_info = OnlineDocumentInfo(
        workspace_name=workspace_name,
        workspace_icon=workspace_icon,
        workspace_id=workspace_id,
        pages=[page],
        total=pages.length(),
    )
    return DatasourceGetPagesResponse(result=[online_document_info])

​

オンラインドライブ

output_schema:
    type: object
    properties:
      file:
        $ref: "https://dify.ai/schemas/v1/file.json"

def _browse_files(
self, request: OnlineDriveBrowseFilesRequest
) -> OnlineDriveBrowseFilesResponse:

credentials = self.runtime.credentials
bucket_name = request.bucket
prefix = request.prefix or ""  # Allow empty prefix for root folder; When you browse the folder, the prefix is the folder id
max_keys = request.max_keys or 10
next_page_parameters = request.next_page_parameters or {}

files = []
files.append(OnlineDriveFile(
    id="", 
    name="", 
    size=0, 
    type="folder" # or "file"
))

return OnlineDriveBrowseFilesResponse(result=[
    OnlineDriveFileBucket(
        bucket="", 
        files=files, 
        is_truncated=False, 
        next_page_parameters={}
    )
])

• prefix：ファイルパスのプレフィックスを表します。例えば、prefix=container1/folder1/はcontainer1バケット内のfolder1フォルダからファイルまたはファイルリストを取得します。
• bucket：ファイルバケットを表します。例えば、bucket=container1はcontainer1バケット内のファイルまたはファイルリストを取得します。このフィールドは、非標準S3プロトコルドライブでは空白のままにできます。
• id：_download_fileメソッドはprefix変数を使用しないため、完全なファイルパスをidに含める必要があります。例えば、id=container1/folder1/file1.txtはcontainer1バケット内のfolder1フォルダからfile1.txtファイルを取得することを示します。

​

プラグインのデバッグ

• プラグインがOAuth認証を使用している場合、リモートデバッグのredirect_uriはローカルプラグインのものとは異なります。サービスプロバイダーのOAuth Appの関連設定を適宜更新してください。
• データソースプラグインはシングルステップデバッグをサポートしていますが、完全な機能を確保するために、完全なナレッジパイプラインでテストすることをお勧めします。

​

最終チェック

• 最小サポートDifyバージョンを1.9.0に設定。
• SDKバージョンをdify-plugin>=0.5.0,<0.6.0に設定。
• README.mdとPRIVACY.mdファイルを作成。
• コードファイルには英語のコンテンツのみを含める。
• デフォルトアイコンをデータソースプロバイダーのロゴに置き換える。

​

パッケージ化と公開

dify plugin package . -o your_datasource.difypkg

• Dify環境にプラグインをインポートして使用する。
• プルリクエストを送信してDify Marketplaceにプラグインを公開する。