azure-search-documents ContentUnderstandingSkill is missing model_name and model_deployment

Open Beginner friendly

#48,555 opened on Aug 12, 2026 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty: 2/5
Estimated time: 1-3 hours
Newbie friendliness: 74/100

Issue type: Bug
Clarity: Clearly specified
Activity status: Quiet
Tech stack: azure, python
Domain: api, backend-api-design

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.

Description

Search Service Attention

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

Install azure-search-documents==12.1.0b1.
Run:

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:

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

model_deployment is likewise absent from the generated model.

Expected behavior

ContentUnderstandingSkill should expose:

model_name: str | None
model_deployment: str | None

and serialize them as:

{
  "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.

Dominant language: Python
Stars: 5.6k
Forks: 3.4k
Avg merge: 1d 22h
Merged PRs (30d): 199

Contributor guide

Open the contributing guide

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.