Azure / Azure/azure-sdk-for-python
Feature Request: Return `chunk_id` in URL Citation Annotations for Azure AI Search Tool
- 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
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