Azure / Azure/azure-sdk-for-python

azure-search-documents ContentUnderstandingSkill is missing model_name and model_deployment

Open Beginner friendly
#48,555 0 comments 1 reaction 0 assignees View on GitHub
needs-triage
Dominant language
Python
Stars
5.6k
Forks
3.4k
Avg merge
1d 21h
Merged PRs (30d)
193

Description

- **Package Name**: azure-search-documents
- **Package Version**: 12.1.0b1
- **Operating System**: macOS 26.6.1 (arm64)
- **Python Version**: 3.13.13

**Describe the bug**

The `ContentUnderstandingSkill` model does not expose the `model_name` and `model_deployment` properties that correspond to the Azure AI Search `2026-05-01-preview` REST properties `modelName` and `modelDeployment`.

These properties enable AI-generated descriptions for document-embedded images, charts, and diagrams. The package defaults to `2026-05-01-preview`, and the same release includes the preview semantic chunking additions, but the Python model cannot represent the image-description configuration.

Service documentation: https://learn.microsoft.com/azure/search/cognitive-search-skill-content-understanding#skill-parameters

**To Reproduce**

1. Install `azure-search-documents==12.1.0b1`.
2. Run:

```python
from azure.search.documents.indexes.models import ContentUnderstandingSkill

ContentUnderstandingSkill(
name="content-understanding",
description="Extract content and describe figures",
context="/document",
inputs=[],
outputs=[],
model_name="gpt-5.4",
model_deployment="gpt-5.4",
)
```

The constructor fails with:

```text
TypeError: ContentUnderstandingSkill.__init__() got an unexpected keyword argument 'model_name'
```

`model_deployment` is likewise absent from the generated model.

**Expected behavior**

`ContentUnderstandingSkill` should expose:

```python
model_name: str | None
model_deployment: str | None
```

and serialize them as:

```json
{
"modelName": "gpt-5.4",
"modelDeployment": "gpt-5.4"
}
```

The service requires both properties to be supplied together.

**Screenshots**

N/A

**Additional context**

The current workaround is to create or update the skillset with a raw `2026-05-01-preview` REST payload through an authenticated SDK client `send_request` call. That works but loses the validation, discoverability, and type safety provided by the generated model.

Contributor guide

Open the contributing guide

Research direction

Start at the ContentUnderstandingSkill model in the azure-search-documents package and compare its generated properties with the Azure AI Search 2026-05-01-preview skill parameters. Add support for modelName and modelDeployment, ensure both serialize correctly, and verify the constructor and serialized payload match the examples in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, python
Domain
api, backend-api-design
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.