User Guide for Manufacturing data solutions Natural Language Query API

Important

Some or all of this functionality is available as part of a preview release. The content and the functionality are subject to change.

Natural Language queries provide a user-friendly way for operations and engineering teams to access manufacturing data without needing data science or IT support. This approach lowers the barrier to answering critical business questions, reduces the time and cost associated with manual data collection and processing, and democratizes access to manufacturing data. It empowers operations personnel to move beyond fixed dashboards and complex user interfaces, giving them the freedom to select, join, and present data as they see fit.

Delivering accurate, timely, and reliable results for natural language queries requires various underlying skills and capabilities. These are all part of the orchestration layer, which includes prompt workflow, intent detection, learning, and post-processing. This document treats the orchestration layer as a black box, focusing instead on how to use the natural language API interface to ask questions or validate the results by comparing actual outcomes with expected ones.

The Industrial AI Copilot Experience is considered an application layer. It can include many different applications and bot frameworks, such as Microsoft Power Virtual Agents and Microsoft Teams Bot Framework, which manage the conversational experience with the user and interact with the API discussed in this document.

Prerequisite knowledge

• Deploy Manufacturing data solutions
• Load Data with User Guide for Manufacturing data solutions Ingestion
• Enable Microsoft Fabric for your organization

Functionality

Let’s now look at the Natural Language Query (NLQ) end to end flow of high level design of a User Question moving via the UI to the Manufacturing data solutions Natural Language Query API where the Prompt Workflow determines the user intent, creates a prompt, using in-context learning for the LLM to send a User Answer via the response of the Natural Language Query API.

This diagram presents a high-level architecture of the process where a user query flows through the User Interface (UI) to the Manufacturing data solutions Natural Language Query API. The Prompt Workflow module interprets the user’s intent, constructs a prompt, and utilizes in-context learning to engage the Large Language Model (LLM). The LLM processes the query and formulates a response, which is then returned as the user's answer via the Natural Language Query API.

1. The idea of a conversational interface is to allow users to ask a question using their natural language to an AI assistant (AI Copilot). This is referred to as an Industry AI Copilot Experience.
2. The AI Copilot passes the natural language question to an NL Query API.
3. The API interacts with an orchestration layer with skills or capabilities to translate the natural language question into a set of entities and vectors that enable the creation of a structured Kusto Query Language (KQL) using a Large Language Model (LLM).
4. This structured query can be applied against the Manufacturing data solutions data estate represented.
5. There's post processing to ground the answers.
6. API responds back to the AI Copilot conversational interface.
7. The AI copilot then responds back to the user with a reliable natural language answer.

How to use natural language queries (NLQ)

There are two principle Natural Query Languages API that this document describes. These two separate API function differently.

• Copilot Query API - The Copilot Query API is the production REST endpoint through which natural language queries are passed from the AI copilot application layer. This API is the surface to which customers and partners can develop and integrate their applications to.
• Copilot Validate API - The Copilot Validate API is a testing and validation REST endpoint used to compare answers provided by Manufacturing data solutions (actuals) with known answers (expected).

Note

Apart from these API, there are some other API to customize the Factory Operations Agent in Azure AI. For more details, refer to Factory Operations Agent in Azure AI extensibility.

The following sections provide a basic example using Curl as the method of interaction with the REST API. You can use any application that supports REST calls. Define what is needed for each API:

• Definition
• Role Required
• Request Headers and Parameters
• Request Body
• Response Codes and JSON
• Example Request and Response

Note

Refer to Get Service URL and Generate an authentication token for detailed instructions.

Note

Refer to the OpenAPI schema files to get all details on how to invoke the different endpoints.

Pipeline V3 API

The V3 pipeline is using more granular instructions, better examples, and an improved query mechanism. All of this causing for higher accuracy and better performance overall.

Query API

Definition

Returns entity data for the provided natural language question. The question is translated into a Kusto Query Language (KQL) query internally and run against the underlying data stores. A response is returned to the client as JSON.

POST https://{serviceUrl}/mds/copilot/v3/query?api-version=2024-06-30-preview

Role required

Manufacturing User

Request headers

Name	Required	Description
Authorization	True	The bearer token used to authenticate the request
User-Agent	True	Short string to identify the client. See here for details
Conversation-ID	False	[Experimental] Session ID for conversation experience

Warning

While it is possible to use the Conversation-Id, this conversational experience is not fully tested with Pipeline V3 and should be considered as experimental.

Request parameters

Name	Required	Type	Default	Description
api-version	True	string	-	The API version to use
includeSummary	False	bool	false	Should summary be included in the response
maxRetry	False	integer	1	Max number to attempts to use for autocorrecting the result
dataTableFormat	False	Enum (Markdown or Json)	Json	The table format to be used in the result in response body

Request payload

{
  "ask": "string" // natural language question
}

Response codes

Code	Name	Description
200	OK	Successful request
400	Bad request	Syntax of the body is incorrect. (Bad body request)
401	Unauthorized	Unable to authenticate the request
403	Forbidden	Insufficient role access: (for example, you don't have the right role or you aren't added to the registration)

Response (JSON)

{
  "result": "string",
  "summary": "string"
}

Example request

{
  "ask": "List all productions orders consuming batch SS-001"
}

Example response

For dataTableFormat=Json and includeSummary=true

{
  "result": "[{\"id\": \"Screw schedule 1548-ISO-10-1-40-SS\"}]",
  "summary": "The production order that consumes batch SS-001 is \"Screw schedule 1548-ISO-10-1-40-SS\"."
}

For dataTableFormat=Markdown and includeSummary=false

{
  "result": "| id |\n| --- |\n| Screw schedule 1548-ISO-10-1-40-SS |",
  "summary": ""
}

Note

For more details, refer to API for extensibility.

Validate API

This API is an asynchronous API to evaluate the accuracy of the Copilot by running a validate test set. The API can be hit with the test set. If the test run is accepted, the endpoint returns a status code 202 (Accepted). A background job starts running through all the test cases provided.

Workflow

The first step is to invoke the Validate endpoint with the expected payload. The status of a testrun can be retrieved afterwards.

POST https://{serviceUrl}/mds/copilot/v3/validate?api-version=2024-06-30-preview

Role required

Manufacturing User

Request headers

Name	Required	Description
Authorization	True	The bearer token used to authenticate the request
User-Agent	True	Short string to identify the client. See here for details

Request parameters

Name	Required	Type	Description
api-version	True	string	The API version to use

Request payload

The payload for this request should be a file with content as shown in the snippet provided.

{
  "testName": "string",
  "runAsConversation": true,
  "testCases": [
    {
      "ask": "string",
      "expectedKQLQuery": "string",
      "skip": false
    },
    // ...
  ]
}

Field	Required	Description
testName	Required	Name of the test. A random GUID is suffixed to the test name to generate unique run ID for every run of the test.
testCases	Required	List of test cases to be executed as part of this test. Each test case needs to have following fields: ask: Natural language query to be tested. expectedKQLQuery: The KQL query which can be run to get expected answer. skip: Boolean to indicate if this test case should be skipped during test run.
runAsConversation	Optional	A boolean value (true or false (default)). If set to true, the Copilot executes the test cases sequentially like a conversation, passing the results as context while executing each subsequent test case. If false or omitted, each testcase is treated as independent question. When set to true, only previous three conversations are passed as context.

Response codes

Code	Name	Description
200	OK	Successful request
400	Bad request	Syntax of the body is incorrect. (Bad body request)
401	Unauthorized	Unable to authenticate the request
403	Forbidden	Insufficient role access: (for example, you don't have the right role or you aren't added to the registration)

Response

The response contains details on the newly created test run. These details are necessary to get the status of the testrun via the other endpoints. Detailed information can be found in the OpenAPI specs.

{
  "testRunId": "TestName_9679b57e836b41e6b3810310653ec2bf", // test run id
  "status": "Accepted", // status of test run
  "createdDate": "2024-07-15T12:08:37.2214552+05:30",
  "createdBy": "Contoso User"
}

Get the status of the testrun

There are two relevant endpoints to get the status. Role required for both endpoints is Manufacturing Admin.

The first one is to get a list of all test runs in a specific time period.

GET https://{serviceUrl}/mds/copilot/v3/validate/test

Examine the OpenAPI specs to learn which parameters can be used for this endpoint.

Note

When there are multiple pages of test runs, the value of header x-ms-continuationtoken can be used for pagination in follow-up requests.

The second one is to get the details of a specific test run.

GET https://{serviceUrl}/mds/copilot/v3/validate/test/{validateTestId}

The value for validateTestId is the identifier retrieved from the response of the Validate endpoint invoked earlier.

Feedback API

Definition

As a standard Microsoft practice to capture user feedback for Copilot responses, an option to give ThumbsUp, ThumbsDown, or Neutral is provided via the User Interface in all the first party Applications. We're extending the same capability to our partners by providing them with an API for the backend implementation of this feature. Copilot Feedback API captures the user driven feedback for our Query API and is used later by partners and Microsoft to analyze and improve the performance and quality of the product.

POST https://{serviceUrl}/mds/copilot/v3/feedback

Request headers

Name	Required	Description
Authorization	True	The bearer token used to authenticate the request

Request parameters

Name	Required	Type	Description	Supported Versions
api-version	True	string	The API version to use	2024-06-30-preview

Request payload

{
  "operationId": "779f8d994a23548dfa13c52a77777de94556",
  "feedback": "ThumbsDown",
  "conversationId": "29f8d994-a235-48df-a13c-52a418a1de91"
}

RequestBody Attributes

• operationId: Consider you made a Copilot Query API call. The response received includes an operation-id header containing a URL. So you need to provide this value so that feedback can be tracked to the Copilot Query API call.

  • type: string
  • required: true

• feedback: The feedback provided by the user.

  • type: enum
  • required: true
  • Supported values are:
    • ThumbsUp
    • ThumbsDown
    • Neutral

• conversationId: The conversationId of the Copilot query API response for which the feedback is being provided.

  • type: string
  • required: false

Response codes

Code	Name	Description
200	OK	Successful request
400	Bad request	Syntax of the body is incorrect. (Bad body request)
401	Unauthorized	Unable to authenticate the request
403	Forbidden	Insufficient role access: (for example, you don't have the right role or you aren't added to the registration)