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 brings SERVICEME's powerful enterprise-level Retrieval-Augmented Generation (RAG) capabilities as a tool to Dify workflows and applications, helping users securely access enterprise knowledge bases and perform contextual retrieval and Q&A within Dify.

Main capabilities include:

  • Perform hybrid, vector, or keyword search on SERVICEME workspaces.
  • Return structured answers, metadata, and workspace context for further processing in subsequent nodes.
  • Support setting workspace scope, similarity threshold, hybrid weights, and reranker models to match enterprise governance policies.
  • Automatically manage OAuth token status to ensure the tool remains callable after token refresh.

Minimum Version & 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.
  • Dify workspace permissions to import and configure custom plugins.

Plugin Installation​

Install via Marketplace​

  1. In the top right corner of the Dify console, click Plugins > Install plugin > Marketplace.

  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, a success prompt will pop up, and the plugin will automatically appear in the Plugins list.

    1760404541818

Install via GitHub​

  1. In the top right corner of the Dify console, click Plugins > Install plugin > GitHub.

    1760341147767

  2. Enter the serviceme-rag-dify 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, confirm the plugin appears in the Plugins list.

    1760341403956

Install via Local difypkg​

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

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

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

    1760341611838

The functionalities of both installation methods are identical. Choose the appropriate method based on your deployment environment's network policy.

Configure OAuth2 Authentication​

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

  1. In the SERVICEME admin panel, enter the super admin 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, then click Use OAuth Authorization in the sidebar.

    1760342001680

  3. In Vendor Configuration, fill in the relevant SERVICEME environment information 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 OpenAPI.

    1760341944086

  4. After saving, if everything is correct, a green verification will be displayed. The plugin will call /openapi/auth/client_with_account to obtain the access token and automatically refresh it when expired.

    1760342139073

To simplify authorization control, the OAuth authorization scope is controlled by the data visibility range of the SERVICEME user role. Refer to the OpenAPI section for details.

Using the SERVICEME RAG Tool in Dify​

  1. Go to Dify's Studio, create a Chatflow workflow, and name it Test SERVICEME.

    1760342428907

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

    1760342539915

  3. After filling in Query String and/or Keywords, the node can be executed.

    1760342726979

  4. Run a debug conversation to verify whether the tool returns the 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. If not entered, can be used with keywords.
keywordsOptional, keywords separated by |.
workspacesOptional, array of SERVICEME workspace IDs to limit the 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 for configuring RRF weights for hybrid retrieval.
rerankerOptional, specify reranker model name. Leave blank to disable reranking.
Note: If your SERVICEME environment does not enable reranker models, be sure to leave this blank

Best Practices​

  • Create separate OAuth2 clients and scopes for different business scenarios to reduce the risk of excessive permissions.
  • Use Dify's version management feature to validate plugin configuration in a sandbox environment before releasing to production.
  • Regularly check plugin logs to promptly detect invocation exceptions.

Troubleshooting​

  1. Authentication Failure
    • Confirm whether client_id and client_secret are correct.
    • Check if the account providing the scope has the correct role set in the corresponding SERVICEME environment.
    • Ensure the Dify server can access the SERVICEME address.
  2. No Data Returned from Tool Invocation
    • Check whether the bound data source has completed synchronization.
    • Adjust retrieval parameters (such as similarity threshold, recall count).
    • Verify whether the calling account is authorized to access the target data.
  3. Plugin Installation Exception
    • Check the Dify plugin logs for error messages.
    • If using local installation, ensure the difypkg file is complete and compatible with the Dify version.
    • Re-download the latest version package and try again.
  4. Third-party Signature
    • If the Dify server is self-hosted and requires third-party plugin signatures, please contact the corresponding Medalsoft (SoftwareOne subsidiary) representative to obtain the public key file for the signature.

Further Reading​