Skip to content

Commit bdef4af

Browse files
Copilotowndev
Copilot
and
owndev
committed
Add documentation for native OpenWebUI citations feature
Co-authored-by: owndev <69784886+owndev@users.noreply.github.com>
1 parent d817d1e commit bdef4af

3 files changed

Lines changed: 207 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@ The functions include a built-in encryption mechanism for sensitive information:
9999
100100
- Enables interaction with **Azure OpenAI** and other **Azure AI** models.
101101
- Supports Azure Search integration for enhanced document retrieval.
102+
- **Native OpenWebUI Citations Support** 🎯: Rich citation cards, source previews, and inline citation correlations for Azure AI Search responses (Azure OpenAI only).
102103
- Supports multiple Azure AI models selection via the `AZURE_AI_MODEL` environment variable (e.g. `gpt-4o;gpt-4o-mini`).
103104
- Customizable pipeline display with configurable prefix via `AZURE_AI_PIPELINE_PREFIX`.
104105
- Azure AI Search / RAG integration with enhanced collapsible citation display (Azure OpenAI only).
@@ -112,6 +113,8 @@ The functions include a built-in encryption mechanism for sensitive information:
112113
113114
🔗 [Learn More About Azure AI](https://azure.microsoft.com/en-us/solutions/ai)
114115
116+
📖 [Azure AI Citations Documentation](./docs/azure-ai-citations.md)
117+
115118
### **2. [N8N Pipeline](./pipelines/n8n/n8n.py)**
116119
117120
> [!TIP]

‎docs/azure-ai-citations.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Azure AI Foundry Pipeline - Native OpenWebUI Citations
2+
3+
This document describes the native OpenWebUI citation support in the Azure AI Foundry Pipeline, which enables rich citation cards and source previews in the OpenWebUI frontend.
4+
5+
## Overview
6+
7+
The Azure AI Foundry Pipeline now supports **native OpenWebUI citations** for Azure AI Search (RAG) responses. This feature enables the OpenWebUI frontend to display:
8+
9+
- **Citation cards** with source information
10+
- **Source previews** with content snippets
11+
- **Inline citation correlations** linking `[doc1]`, `[doc2]` markers to their sources
12+
- **Interactive citation UI** with clickable sources
13+
14+
## Features
15+
16+
### Dual Citation Modes
17+
18+
The pipeline supports two modes for displaying citations:
19+
20+
1. **Native OpenWebUI Citations** (new): Structured citation events and fields for frontend consumption
21+
2. **Markdown/HTML Citations** (existing): Collapsible HTML details with formatted citation information
22+
23+
Both modes can be enabled simultaneously or independently via configuration.
24+
25+
### Configuration Options
26+
27+
| Environment Variable | Default | Description |
28+
|---------------------|---------|-------------|
29+
| `AZURE_AI_OPENWEBUI_CITATIONS` | `true` | Enable native OpenWebUI citation events and fields |
30+
| `AZURE_AI_ENHANCE_CITATIONS` | `true` | Enable markdown/HTML citation display (collapsible sections) |
31+
32+
### How It Works
33+
34+
#### Streaming Responses
35+
36+
When Azure AI Search returns citations in a streaming response:
37+
38+
1. The pipeline detects citations in the SSE (Server-Sent Events) stream
39+
2. **If `AZURE_AI_OPENWEBUI_CITATIONS` is enabled**: Citation events are emitted immediately via `__event_emitter__`
40+
3. **If `AZURE_AI_ENHANCE_CITATIONS` is enabled**: A formatted markdown/HTML citation section is appended at the end of the stream
41+
42+
#### Non-Streaming Responses
43+
44+
When Azure AI Search returns citations in a non-streaming response:
45+
46+
1. The pipeline extracts citations from the response
47+
2. **If `AZURE_AI_OPENWEBUI_CITATIONS` is enabled**: An `openwebui_citations` field is attached to the response root
48+
3. **If `AZURE_AI_ENHANCE_CITATIONS` is enabled**: The response content is enhanced with a formatted citation section
49+
50+
## Citation Format
51+
52+
### OpenWebUI Citation Event Structure
53+
54+
Citation events follow the OpenWebUI specification:
55+
56+
```python
57+
{
58+
"type": "citation",
59+
"data": {
60+
"id": "doc1", # Unique identifier (matches inline tokens)
61+
"token": "doc1", # Token for correlation (e.g., [doc1])
62+
"title": "Document Title", # Source name/title
63+
"document": ["..."], # Content array
64+
"metadata": [{}], # Metadata array
65+
"source": {
66+
"name": "Document Title",
67+
"url": "https://..." # Optional
68+
},
69+
"url": "https://...", # Optional: document URL
70+
"filepath": "/path/to/file", # Optional: file path
71+
"preview": "Content snippet...", # Optional: content preview
72+
"chunk_id": "chunk-123", # Optional: chunk identifier
73+
"score": 0.95 # Optional: relevance score
74+
}
75+
}
76+
```
77+
78+
### Azure Citation Format (Input)
79+
80+
Azure AI Search returns citations in this format:
81+
82+
```python
83+
{
84+
"title": "Document Title",
85+
"content": "Full or partial content",
86+
"url": "https://...",
87+
"filepath": "/path/to/file",
88+
"chunk_id": "chunk-123",
89+
"score": 0.95,
90+
"metadata": {}
91+
}
92+
```
93+
94+
The pipeline automatically converts Azure citations to OpenWebUI format.
95+
96+
## Usage Examples
97+
98+
### Basic Setup with Native Citations
99+
100+
```python
101+
# Enable native OpenWebUI citations (default)
102+
AZURE_AI_OPENWEBUI_CITATIONS=true
103+
104+
# Optionally disable markdown/HTML citations if you only want native citations
105+
AZURE_AI_ENHANCE_CITATIONS=false
106+
```
107+
108+
### Both Citation Modes Enabled (Default)
109+
110+
```python
111+
# Enable both native and markdown/HTML citations (default)
112+
AZURE_AI_OPENWEBUI_CITATIONS=true
113+
AZURE_AI_ENHANCE_CITATIONS=true
114+
```
115+
116+
This configuration provides:
117+
- Native citation cards in the OpenWebUI frontend
118+
- Markdown/HTML citation section as fallback for non-supported clients
119+
120+
### Only Markdown/HTML Citations (Legacy)
121+
122+
```python
123+
# Disable native citations, use only markdown/HTML
124+
AZURE_AI_OPENWEBUI_CITATIONS=false
125+
AZURE_AI_ENHANCE_CITATIONS=true
126+
```
127+
128+
## Implementation Details
129+
130+
### Helper Functions
131+
132+
The pipeline includes three new helper functions:
133+
134+
1. **`_extract_citations_from_response()`**: Extracts citations from Azure responses
135+
2. **`_normalize_citation_for_openwebui()`**: Converts Azure citations to OpenWebUI format
136+
3. **`_emit_openwebui_citation_events()`**: Emits citation events via `__event_emitter__`
137+
138+
### Title Fallback Logic
139+
140+
The pipeline uses intelligent title fallback:
141+
142+
1. Use `title` field if available
143+
2. Fallback to `filepath` if title is empty
144+
3. Fallback to `url` if both title and filepath are empty
145+
4. Fallback to `"Unknown Document"` if all are empty
146+
147+
This ensures every citation has a meaningful display name.
148+
149+
### Streaming Citation Emission
150+
151+
Citations are emitted **as soon as they are detected** in the stream, ensuring:
152+
- Low latency for citation display
153+
- Frontend can start rendering citations while content is still streaming
154+
- No waiting for the complete response
155+
156+
### Backward Compatibility
157+
158+
The implementation maintains full backward compatibility:
159+
160+
- Existing markdown/HTML citation display continues to work
161+
- No breaking changes to the API
162+
- Both citation modes can be enabled simultaneously
163+
- Default configuration enables both modes
164+
165+
## Troubleshooting
166+
167+
### Citations Not Appearing
168+
169+
**Problem**: Citations don't appear in the OpenWebUI frontend
170+
171+
**Solutions**:
172+
1. Verify `AZURE_AI_OPENWEBUI_CITATIONS=true` is set
173+
2. Check that Azure AI Search is properly configured (`AZURE_AI_DATA_SOURCES`)
174+
3. Ensure you're using an Azure OpenAI endpoint (not a generic Azure AI endpoint)
175+
4. Check browser console for errors
176+
177+
### Citation Cards vs. Markdown Section
178+
179+
**Problem**: Seeing both citation cards and markdown section
180+
181+
**Solution**: This is the default behavior. To show only citation cards:
182+
```bash
183+
AZURE_AI_OPENWEBUI_CITATIONS=true
184+
AZURE_AI_ENHANCE_CITATIONS=false
185+
```
186+
187+
### Missing Citation Metadata
188+
189+
**Problem**: Some citation fields (URL, filepath, score) are missing
190+
191+
**Solution**: These fields are optional. Azure AI Search may not return all fields depending on your index configuration. The pipeline gracefully handles missing fields.
192+
193+
## References
194+
195+
- [OpenWebUI Pipelines Citation Feature Discussion](https://github.com/open-webui/pipelines/issues/229)
196+
- [OpenWebUI Event Emitter Documentation](https://docs.openwebui.com/features/plugin/development/events)
197+
- [Azure AI Search Documentation](https://learn.microsoft.com/en-us/azure/search/)
198+
199+
## Version History
200+
201+
- **v2.6.0**: Added native OpenWebUI citations support
202+
- **v2.5.x**: Markdown/HTML citation display only

‎pipelines/azure/azure_ai_foundry.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
author_url: https://github.com/owndev/
55
project_url: https://github.com/owndev/Open-WebUI-Functions
66
funding_url: https://github.com/sponsors/owndev
7-
version: 2.5.2
7+
version: 2.6.0
88
license: Apache License 2.0
99
description: A pipeline for interacting with Azure AI services, enabling seamless communication with various AI models via configurable headers and robust error handling. This includes support for Azure OpenAI models as well as other Azure AI models by dynamically managing headers and request configurations. Azure AI Search (RAG) integration is only supported with Azure OpenAI endpoints.
1010
features:
@@ -16,6 +16,7 @@
1616
- Predefined models for easy access.
1717
- Encrypted storage of sensitive API keys
1818
- Azure AI Search / RAG integration with enhanced citation display (Azure OpenAI only)
19+
- Native OpenWebUI citations support with structured events and citation cards (Azure OpenAI only)
1920
"""
2021

2122
from typing import (

0 commit comments

Comments
 (0)