Skip to main content

Dify Integration

Overview​

Dify is an open-source large language model (LLM) application development platform. It integrates the concepts of Backend as Service and LLMOps, enabling developers to quickly build production-grade generative AI applications.

The serviceme-rag-dify plugin provided by SERVICEME offers SERVICEME’s powerful enterprise-grade Retrieval-Augmented Generation (RAG) capabilities as a tool for Dify workflows and applications, helping users securely access enterprise knowledge bases, perform contextual retrieval, and Q&A within Dify.

Key capabilities include:

  • Performing hybrid, vector, or keyword retrieval on SERVICEME workspaces.
  • Returning structured answers, metadata, and workspace context for further processing in subsequent nodes.
  • Supporting configuration of workspace scope, similarity threshold, hybrid weights, and reranker models to align with enterprise governance policies.
  • Automatically managing OAuth token status to ensure tool calls remain valid after token refresh.

Minimum Version and Prerequisites​

  • Minimum supported version: Dify ≥ 1.9.0.
  • Accessible SERVICEME environment with OpenAPI permissions enabled.
  • OAuth2 credentials (client_id, client_secret, user account) created according to the SERVICEME OpenAPI Authentication Guide.
  • Permissions to import and configure custom plugins in the Dify workspace.

Plugin Installation​

Installation via Marketplace​

  1. Click Plugins > Install plugin > Marketplace at the top right corner of the Dify console.

  2. Enter SERVICEME RAG in the search box and press Enter.

    1760404492148

  3. Hover over the first result (SERVICEME RAG) and click Install.

  4. After installation completes, a success prompt will appear, and the plugin will automatically show up in the Plugins list.

    1760404541818

Installation via GitHub​

  1. Click Plugins > Install plugin > GitHub at the top right corner of the Dify console.

    1760341147767

  2. Enter the repository address https://github.com/medalsoftchina/serviceme-rag-dify and click Next. 1760341264672

  3. Select the corresponding version and plugin file, then click Next.

    1760341328820

  4. After installation completes, verify the plugin appears in the Plugins list.

    1760341403956

Installation via Local difypkg​

  1. Visit the GitHub repository’s Release page and download the latest serviceme-rag-dify.difypkg.

  2. In the Dify console, select Plugins > Install plugin > Local Package Plugin, and upload the downloaded package.

  3. After successful installation, confirm the success prompt appears.

    1760341611838

Both installation methods provide identical functionality; choose the appropriate method based on your deployment environment’s network policies.

Configuring OAuth2 Authentication​

The SERVICEME plugin uses OAuth2 to access SERVICEME OpenAPI resources. Please configure as follows:

  1. In the SERVICEME admin portal, enter the super administrator interface. The system administrator creates credentials via the client management interface {domain}#/super-admin/client-management, generating client_id and client_secret.

    1760342955196

  2. In the Dify console, click the plugin and then click Use OAuth Authorization in the sidebar.

    1760342001680

  3. Fill in the SERVICEME environment information in Vendor Configuration and click Save and Authorize:

    • Base URL: SERVICEME domain (including protocol), e.g., https://example.serviceme.com.
    • Client Id / Client Secret: Credentials from the client management interface.
    • Account: SERVICEME username used to call the OpenAPI.

    1760341944086

  4. After saving, if everything is correct, a green verification success will be shown. The plugin will call /openapi/auth/client_with_account to obtain an access token and automatically refresh it upon expiration.

    1760342139073

To simplify authorization control, OAuth authorization scope can be controlled via user roles and SERVICEME data visibility. Refer to the OpenAPI section for details.

Calling SERVICEME RAG Tool in Dify​

  1. Go to Dify’s Studio, create a Chatflow workflow named Test SERVICEME.

    1760342428907

  2. On the canvas, click Add Node > Tools > serviceme-rag.

    1760342539915

  3. Fill in the Query String and/or Keywords to enable execution of this node.

    1760342726979

  4. Run and debug the conversation to verify whether the tool returns expected results.

Parameter Description​

After adding the serviceme-rag tool to a node, you can adjust retrieval behavior with the following parameters:

Input ItemDescription
queryOptional, natural language query; can be used with keywords if not entered.
keywordsOptional, keywords separated by |.
workspacesOptional, array of SERVICEME workspace IDs to limit search scope.
top_kRequired, number of results to return.
rag_objectRequired, retrieval object: both, qna, or doc.
rag_modeRequired, retrieval mode: hybrid, embedding, or fulltext.
min_similarityOptional, similarity threshold, range 0~1, default 0.8.
metadata_filterOptional, metadata filter, currently supports default.
weightsOptional, JSON configuration of RRF weights for hybrid retrieval.
rerankerOptional, specify reranker model name; leave empty to disable reranking.
Note: If your SERVICEME environment does not enable reranker models, please leave this empty.

Best Practices​

  • Create separate OAuth2 clients and scopes for different business scenarios to reduce over-privilege risks.
  • Use Dify’s version management to verify plugin configuration in sandbox before production release.
  • Regularly check plugin logs to promptly detect call anomalies.

Troubleshooting​

  1. Authentication Failure
    • Verify client_id and client_secret are correct.
    • Check that the account providing the scope has the correct role in the corresponding SERVICEME environment.
    • Ensure the Dify server can access the SERVICEME address.
  2. No Data Returned from Tool Call
    • Check if the bound data source has completed synchronization.
    • Adjust retrieval parameters (e.g., similarity threshold, recall count).
    • Verify the calling account is authorized to access the target data.
  3. Plugin Installation Issues
    • Check Dify plugin logs for error messages.
    • For local installation, ensure the difypkg file is complete and compatible with the Dify version.
    • Re-download the latest package and retry.
  4. Third-Party Signing
    • If the Dify server is self-hosted and requires third-party plugin signing, please contact Medalsoft (SoftwareOne subsidiary) customer representative to obtain the signed public key file.

Further Reading​