You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An [enrichment pipeline](cognitive-search-concept-intro.md) can include both [built-in skills](cognitive-search-predefined-skills.md) and [custom skills](cognitive-search-custom-skill-web-api.md) that you personally create and publish. Your custom code executes externally to the search service (for example, as an Azure function), but accepts inputs and sends outputs to the skillset just like any other skill.
16
16
17
-
An [enrichment pipeline](cognitive-search-concept-intro.md) in Azure Cognitive Search can be assembled from [built-in cognitive skills](cognitive-search-predefined-skills.md) as well as [custom skills](cognitive-search-custom-skill-web-api.md)that you personally create and add to the pipeline. In this article, learn how to create a custom skill that exposes an interface allowing it to be included in an AI enrichment pipeline.
17
+
If you are building a custom skill, this article describes the interface you'll use to integrate the skill into the pipeline. The primary requirement is the ability to accept inputs and emit outputs in ways that are consumable within the [skillset](cognitive-search-defining-skillset.md)as a whole. As such, the focus of this article is on the input and output formats that the enrichment pipeline requires.
18
18
19
-
Building a custom skill gives you a way to insert transformations unique to your content. A custom skill executes independently, applying whatever enrichment step you require. For example, you could define field-specific custom entities, build custom classification models to differentiate business and financial contracts and documents, or add a speech recognition skill to reach deeper into audio files for relevant content. For a step-by-step example, see [Example: Creating a custom skill for AI enrichment](cognitive-search-create-custom-skill-example.md).
19
+
## Benefits of custom skills
20
20
21
-
Whatever custom capability you require, there is a simple and clear interface for connecting a custom skill to the rest of the enrichment pipeline. The only requirement for inclusion in a [skillset](cognitive-search-defining-skillset.md) is the ability to accept inputs and emit outputs in ways that are consumable within the skillset as a whole. The focus of this article is on the input and output formats that the enrichment pipeline requires.
21
+
Building a custom skill gives you a way to insert transformations unique to your content. A custom skill executes independently, applying whatever enrichment step you require. For example, you could build custom classification models to differentiate business and financial contracts and documents, or add a speech recognition skill to reach deeper into audio files for relevant content. For a step-by-step example, see [Example: Creating a custom skill for AI enrichment](cognitive-search-create-custom-skill-example.md).
22
22
23
-
## Web API custom skill interface
23
+
## Set the endpoint and timeout interval
24
24
25
-
Custom WebAPI skill endpoints by default timeout if they don't return a response within a 30 second window. The indexing pipeline is synchronous and indexing will produce a timeout error if a response is not received in that window. It is possible to configure the timeout to be up to 230 seconds, by setting the timeout parameter:
25
+
The interface for a custom skill is specified through the [Custom WebAPI skill](cognitive-search-custom-skill-web-api.md).
26
+
27
+
By default, the connection to the endpoint will time out if a response is not returned within a 30-second window. The indexing pipeline is synchronous and indexing will produce a timeout error if a response is not received in that time frame. You can increase the interval to a maximum value of 230 seconds by setting the timeout parameter:
"description": "This skill has a 230 second timeout",
32
+
"uri": "https://[your custom skill uri goes here]",
33
+
"timeout": "PT230S",
32
34
```
33
35
34
-
Make sure the URI is secure (HTTPS).
35
-
36
-
Currently, the only mechanism for interacting with a custom skill is through a Web API interface. The Web API needs must meet the requirements described in this section.
37
-
38
-
### 1. Web API Input Format
36
+
When setting the URI, make sure the URI is secure (HTTPS).
The Web API must accept an array of records to be processed. Each record must contain a property bag that is the input provided to your Web API.
42
41
42
+
Suppose you want to create a simple enricher that identifies the first date mentioned in the text of a contract. In this example, the custom skill accepts a single input "contractText" as the contract text. The skill also has a single output, which is the date of the contract. To make the enricher more interesting, return this "contractDate" in the shape of a multi-part complex type.
43
43
44
-
The Web API must accept an array of records to be processed. Each record must contain a "property bag" that is the input provided to your Web API.
44
+
Your Web API should be ready to receive a batch of input records. Each member of the "values" array represents the input for a particular record. Each record is required to have the following elements:
45
45
46
-
Suppose you want to create a simple enricher that identifies the first date mentioned in the text of a contract. In this example, the skill accepts a single input *contractText* as the contract text. The skill also has a single output, which is the date of the contract. To make the enricher more interesting, return this *contractDate* in the shape of a multi-part complex type.
46
+
+ A "recordId" member that is the unique identifier for a particular record. When your enricher returns the results, it must provide this "recordId" in order to allow the caller to match the record results to their input.
47
47
48
-
Your Web API should be ready to receive a batch of input records. Each member of the *values* array represents the input for a particular record. Each record is required to have the following elements:
48
+
+ A "data" member, which is essentially a bag of input fields for each record.
49
49
50
-
+ A *recordId* member that is the unique identifier for a particular record. When your enricher returns the results, it must provide this *recordId* in order to allow the caller to match the record results to their input.
51
-
52
-
+ A *data* member, which is essentially a bag of input fields for each record.
53
-
54
-
To be more concrete, per the example above, your Web API should expect requests that look like this:
50
+
The resulting Web API request might look like this:
55
51
56
52
```json
57
53
{
@@ -82,11 +78,12 @@ To be more concrete, per the example above, your Web API should expect requests
82
78
]
83
79
}
84
80
```
85
-
In reality, your service may get called with hundreds or thousands of records instead of only the three shown here.
86
81
87
-
### 2. Web API Output Format
82
+
In practice, your code may get called with hundreds or thousands of records instead of only the three shown here.
83
+
84
+
## Format Web API outputs
88
85
89
-
The format of the output is a set of records containing a *recordId*, and a property bag
86
+
The format of the output is a set of records containing a "recordId", and a property bag. This particular example has only one output, but you could output more than one property. As a best practice, consider returning error and warning messages if a record could not be processed.
90
87
91
88
```json
92
89
{
@@ -117,15 +114,9 @@ The format of the output is a set of records containing a *recordId*, and a prop
117
114
}
118
115
```
119
116
120
-
This particular example has only one output, but you could output more than one property.
117
+
## Add a custom skill to a skillset
121
118
122
-
### Errors and Warning
123
-
124
-
As shown in the previous example, you may return error and warning messages for each record.
125
-
126
-
## Consuming custom skills from skillset
127
-
128
-
When you create a Web API enricher, you can describe HTTP headers and parameters as part of the request. The snippet below shows how request parameters and *optional* HTTP headers may be described as part of the skillset definition. HTTP headers are not a requirement, but they allow you to add additional configuration capabilities to your skill and to set them from the skillset definition.
119
+
When you create a Web API enricher, you can describe HTTP headers and parameters as part of the request. The snippet below shows how request parameters and optional HTTP headers can be included in the skillset definition. Setting an HTTP header is useful if you need to pass configuration settings to your code.
129
120
130
121
```json
131
122
{
@@ -155,11 +146,16 @@ When you create a Web API enricher, you can describe HTTP headers and parameters
155
146
}
156
147
```
157
148
149
+
## Watch this video
150
+
151
+
For a video introduction and demo, watch the following demo.
This article covered the interface requirements necessary for integrating a custom skill into a skillset. Click the following links to learn more about custom skills and skillset composition.
157
+
This article covered the interface requirements necessary for integrating a custom skill into a skillset. Continue with these links to learn more about custom skills and skillset composition.
161
158
162
-
+[Watch our video about custom skills](https://youtu.be/fHLCE-NZeb4)
163
159
+[Power Skills: a repository of custom skills](https://github.com/Azure-Samples/azure-search-power-skills)
164
160
+[Example: Creating a custom skill for AI enrichment](cognitive-search-create-custom-skill-example.md)
165
161
+[How to define a skillset](cognitive-search-defining-skillset.md)
Copy file name to clipboardExpand all lines: articles/search/search-what-is-azure-search.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,14 +61,16 @@ For more information about specific functionality, see [Features of Azure Cognit
61
61
62
62
## How to get started
63
63
64
-
An end-to-end exploration of core search features can be achieved in four steps:
64
+
An end-to-end exploration of core search features can be accomplished in four steps:
65
65
66
66
1.[**Choose a tier**](search-sku-tier.md). One free search service is allowed per subscription. All quickstarts can be completed on the free tier. For more capacity and capabilities, you will need a [billable tier](https://azure.microsoft.com/pricing/details/search/).
67
67
68
68
1.[**Create a search service**](search-create-service-portal.md) in the Azure portal.
69
69
70
70
1.[**Start with Import data wizard**](search-get-started-portal.md). Choose a built-in sample data source to create, load, and query an index in minutes.
71
71
72
+
1.[**Finish with Search Explorer**](search-explorer.md), using a portal client to query the search index you just created.
73
+
72
74
Alternatively, you can create, load, and query a search index in separate steps:
73
75
74
76
1.[**Create a search index**](search-what-is-an-index.md) using the portal, [REST API](/rest/api/searchservice/create-index), [.NET SDK](search-howto-dotnet-sdk.md), or another SDK. The index schema defines the structure of searchable content.
0 commit comments