Azure / Azure/azure-sdk-for-python

Feature Request: Return `chunk_id` in URL Citation Annotations for Azure AI Search Tool

Offen
#44,670 2 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen
AI Projects customer-reported needs-team-attention question Service Attention
Vorherrschende Sprache
Python
Sterne
5.6k
Forks
3.4k
Ø Merge
2 T. 2 Std.
Gemergte PRs (30 T.)
213

Beschreibung

## Is your feature request related to a problem? Please describe.

When using `AzureAISearchAgentTool` with the Azure AI Projects SDK (Responses API), the agent returns citations via `url_citation` annotations in the response. These annotations include:
- `start_index` / `end_index` - position in the response text
- `url` - the search service URL
- `title` - document name (e.g., "doc_2")

However, there is **no way to map a specific citation back to the exact chunk** that was retrieved from Azure AI Search. The `title` field only provides the document name, not the specific chunk within that document.

**Example current annotation:**
```python
annotation.type = "url_citation"
annotation.url = "https://mysearch.search.windows.net/"
annotation.title = "doc_2" # Which chunk
annotation.start_index = 558
annotation.end_index = 570
```

## Describe the solution you'd like

Add a `chunk_id` (or `result_id` / `source_id`) field to the `url_citation` annotation that maps directly to the specific chunk from the Azure AI Search results.

**Proposed annotation structure:**
```python
annotation.type = "url_citation"
annotation.url = "https://mysearch.search.windows.net/"
annotation.title = "doc_2"
annotation.chunk_id = "" # <-- NEW: Specific chunk identifier
annotation.start_index = 558
annotation.end_index = 570
```

This would allow developers to:
1. Trace exactly which chunk the model used for each citation
2. Retrieve the full chunk content from their search index
3. Build proper citation UIs with accurate source linking
4. Implement evaluation/debugging for RAG applications

## Differentiation from Related Issue

This request is **different from [#42218](https://github.com/Azure/azure-sdk-for-python/issues/42218)**, which asks for search results to be returned per tool call.

| Issue | Scope | Use Case |
|-------|-------|----------|
| #42218 | Return all search results for each tool call | See what chunks were retrieved |
| **This request** | Return chunk_id per annotation/citation | Map each citation to its specific source chunk |

Even if #42218 is implemented, without chunk IDs in annotations, there's no reliable way to correlate which retrieved chunk corresponds to which citation in the response.

## Describe alternatives you've considered

N/A

## Additional context

**SDK versions:**
- `azure-ai-projects>=2.0.0b1`
- Using `AzureAISearchAgentTool` with `openai_client.responses.create(stream=True)`

**Current output showing the gap:**
```
📝 Citations in Response:
Citation:
Referenced Text: '【4:2†source】'
URL: https://mysearch.search.windows.net/
Title: doc_2 # <-- no chunk ID
Position: [558:570]
```

**Expected behavior:**
Each `url_citation` annotation should include a `chunk_id` field that uniquely identifies the source chunk, enabling precise citation-to-source mapping.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne damit, die Ausgabe von AzureAISearchAgentTool bis zu den url_citation-Annotationen der Responses API nachzuverfolgen, insbesondere bei der Verwendung von openai_client.responses.create(stream=True). Vergleiche das angeforderte chunk_id-Mapping mit dem verwandten Issue #42218 und überprüfe, welche Metadaten des Azure AI Search-Ergebnisses verfügbar sind. Als erledigt gilt die Aufgabe, wenn jede Citation ihren spezifischen abgerufenen Chunk identifizieren kann, ohne bestehende Annotationsfelder zu beeinträchtigen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
azure, python
Bereich
api, backend
Issue-Typ
Feature
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
45/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.