fix(search): protect WebIQ result fields and simplify endpoint configuration

This commit is contained in:
Gilad Katz 2026-09-23 01:15:51 +03:00
parent 92d30bf16b
commit 30104f38ce
3 changed files with 86 additions and 94 deletions

View file

@ -1,78 +0,0 @@
# Microsoft Web IQ search
Use `search_provider="webiq"` with a Microsoft Web IQ API key. This integration calls the [Web Search v3 REST API](https://webiq.microsoft.ai/documentation/api-reference/web/), which is separate from Grounding with Bing
Set `WEBIQ_API_KEY` in the process environment or pass `api_key` explicitly. The provider sends it in the `x-apikey` header. This initial integration uses API-key authentication; it does not acquire or refresh Entra ID tokens
```python
import asyncio
from litellm import asearch, search
result = search(
query="retrieval augmented generation research",
search_provider="webiq",
max_results=5,
country="US",
)
print(result.model_dump())
async def main():
result = await asearch(query="retrieval augmented generation research", search_provider="webiq")
print(result.model_dump())
asyncio.run(main())
```
The provider requests `contentFormat="passage"` and `maxLength=5000` by default, following the [Web IQ quick start](https://webiq.microsoft.ai/documentation/). `content` becomes the standard result's `snippet`, while `lastUpdatedAt` supplies `date` and `last_updated` when available. Crawl timestamps are preserved as `crawledAt`, not presented as publication dates. Other response metadata, including `traceId` and instrumentation fields, is preserved; the integration does not send instrumentation pings
## Gateway
Add this search tool to your existing proxy configuration:
```yaml
search_tools:
- search_tool_name: webiq-search
litellm_params:
search_provider: webiq
api_key: os.environ/WEBIQ_API_KEY
```
Set `LITELLM_PROXY_URL` to your existing LiteLLM deployment URL, without a trailing slash. This is the gateway URL your application calls; the provider itself calls `https://api.microsoft.ai/v3/search/web`
```bash
curl "$LITELLM_PROXY_URL/v1/search/webiq-search" \
-H "Authorization: Bearer $LITELLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"retrieval augmented generation research","max_results":5}'
```
To select Web IQ for existing web-search interception, merge these settings into the proxy configuration. Set `enabled_providers` to the model providers used by your application; this example selects Bedrock
```yaml
litellm_settings:
callbacks:
- websearch_interception
websearch_interception_params:
search_tool_name: webiq-search
enabled_providers: ["bedrock"]
```
The existing interception implementation controls supported client endpoints, tool conversion, streaming, and model continuation. Selecting Web IQ does not add a separate agentic loop
## Parameters
| LiteLLM parameter | Web IQ request |
| --- | --- |
| `query` | `query`; a list of queries is joined with spaces |
| `max_results` | `maxResults` |
| `country` | `region`, uppercased |
| `search_domain_filter` | `site:` query operators, with `-domain` entries mapped to `-site:` exclusions |
| `max_tokens_per_page` | Not forwarded; Web IQ's `maxLength` measures characters, not tokens |
Pass native options such as `language`, `region`, `location`, `contentFormat`, `maxLength`, `maxResults`, and `safeSearch` as keyword arguments. Explicit native values override mapped values and integration defaults. Web IQ validates its own parameter limits
Domain filters narrow search relevance. Microsoft also notes that `site:` queries can return adult content regardless of `safeSearch`; see the API reference before relying on domain filtering in a restricted-content application
The default API base is `https://api.microsoft.ai/v3`. `api_base` or the operator's `WEBIQ_API_BASE` can select a different base, with `/search/web` appended once. A caller-selected host cannot receive a server-managed API key unless the host matches the default or operator-configured base; pass explicit credentials for an intentional override
No default Web IQ price is registered by this integration. Do not interpret missing cost data as free usage. Live Web IQ validation requires an enabled account and a valid API key

View file

@ -7,7 +7,6 @@ import httpx
from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
from litellm.llms.base_llm.search.transformation import BaseSearchConfig, SearchResponse, SearchResult
from litellm.secret_managers.main import get_secret_str
if TYPE_CHECKING:
from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
@ -44,7 +43,7 @@ def _query_with_domains(query: str, domains: object) -> str:
class WebIQSearchConfig(BaseSearchConfig):
WEBIQ_API_BASE: Final = "https://api.microsoft.ai/v3"
DEFAULT_API_BASE: Final = "https://api.microsoft.ai/v3"
@staticmethod
def ui_friendly_name() -> str:
@ -61,8 +60,8 @@ class WebIQSearchConfig(BaseSearchConfig):
caller_api_key=api_key,
caller_api_base=api_base,
key_env_vars=("WEBIQ_API_KEY",),
base_env_var="WEBIQ_API_BASE",
default_api_base=self.WEBIQ_API_BASE,
base_env_var=None,
default_api_base=self.DEFAULT_API_BASE,
)
if not resolved_key:
raise ValueError("Set WEBIQ_API_KEY or pass api_key for Microsoft Web IQ search")
@ -79,7 +78,7 @@ class WebIQSearchConfig(BaseSearchConfig):
data: dict[str, object] | list[dict[str, object]] | None = None, # mutable-ok: BaseSearchConfig interface
**kwargs: object, # kwargs-ok: BaseSearchConfig interface
) -> str:
base: Final = (api_base or get_secret_str("WEBIQ_API_BASE") or self.WEBIQ_API_BASE).rstrip("/")
base: Final = (api_base or self.DEFAULT_API_BASE).rstrip("/")
return base if base.endswith("/search/web") else f"{base}/search/web"
def transform_search_request(
@ -135,9 +134,21 @@ class WebIQSearchConfig(BaseSearchConfig):
snippet=result.content,
date=result.lastUpdatedAt or None,
last_updated=result.lastUpdatedAt or None,
**(result.model_extra or MappingProxyType({})),
**MappingProxyType(
{
key: value
for key, value in (result.model_extra or MappingProxyType({})).items()
if key not in SearchResult.model_fields
}
),
)
for result in parsed.webResults
],
**(parsed.model_extra or MappingProxyType({})),
**MappingProxyType(
{
key: value
for key, value in (parsed.model_extra or MappingProxyType({})).items()
if key not in SearchResponse.model_fields
}
),
)

View file

@ -13,7 +13,6 @@ from litellm.llms.webiq.search.transformation import WebIQSearchConfig
@pytest.fixture(autouse=True)
def webiq_environment(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
monkeypatch.delenv("WEBIQ_API_KEY", raising=False)
monkeypatch.delenv("WEBIQ_API_BASE", raising=False)
monkeypatch.setattr( # test-quality-ok: select HTTPX so respx can intercept the external HTTP boundary
litellm, "disable_aiohttp_transport", True
)
@ -23,7 +22,7 @@ def webiq_environment(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
def test_search_maps_request_and_preserves_sources(respx_mock: respx.MockRouter) -> None:
endpoint: Final = f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web"
endpoint: Final = f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web"
route: Final = respx_mock.post(endpoint).respond(
json={
"webResults": [
@ -82,12 +81,11 @@ def test_search_maps_request_and_preserves_sources(respx_mock: respx.MockRouter)
}
async def test_asearch_uses_environment_credentials_and_custom_endpoint(
async def test_asearch_uses_environment_credentials_at_default_endpoint(
respx_mock: respx.MockRouter, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setenv("WEBIQ_API_KEY", "environment-key")
monkeypatch.setenv("WEBIQ_API_BASE", "https://webiq.example/v3/")
route: Final = respx_mock.post("https://webiq.example/v3/search/web").respond(json={"webResults": []})
route: Final = respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond(json={"webResults": []})
response: Final = await litellm.asearch(query="no matches", search_provider="webiq")
@ -100,9 +98,25 @@ async def test_asearch_uses_environment_credentials_and_custom_endpoint(
}
async def test_asearch_uses_explicit_credentials_at_custom_endpoint(respx_mock: respx.MockRouter) -> None:
route: Final = respx_mock.post("https://webiq.example/v3/search/web").respond(json={"webResults": []})
response: Final = await litellm.asearch(
query="no matches", search_provider="webiq", api_key="custom-key", api_base="https://webiq.example/v3/"
)
assert response.model_dump() == {"object": "search", "results": []}
assert route.calls.last.request.headers["x-apikey"] == "custom-key"
assert json.loads(route.calls.last.request.content) == {
"query": "no matches",
"contentFormat": "passage",
"maxLength": 5000,
}
@pytest.mark.parametrize("updated", [None, "", "2026-02-01T00:00:00Z"])
def test_optional_updated_date_never_uses_crawl_time(respx_mock: respx.MockRouter, updated: str | None) -> None:
respx_mock.post(f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web").respond(
respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond(
json={
"webResults": [
{
@ -120,7 +134,7 @@ def test_optional_updated_date_never_uses_crawl_time(respx_mock: respx.MockRoute
def test_missing_optional_dates_and_result_order(respx_mock: respx.MockRouter) -> None:
respx_mock.post(f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web").respond(
respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond(
json={
"webResults": [
{"title": title, "url": f"https://example.com/{title}", "content": title}
@ -137,7 +151,7 @@ def test_missing_optional_dates_and_result_order(respx_mock: respx.MockRouter) -
@pytest.mark.parametrize("body", ["not json", "{}", '{"webResults": null}', '{"webResults": [{}]}'])
def test_malformed_response_is_not_reported_as_empty_success(respx_mock: respx.MockRouter, body: str) -> None:
respx_mock.post(f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web").respond(text=body)
respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond(text=body)
with pytest.raises(openai.APIError, match="invalid search response") as error:
litellm.search(query="query", search_provider="webiq", api_key="key")
assert error.value.status_code == 502
@ -145,7 +159,7 @@ def test_malformed_response_is_not_reported_as_empty_success(respx_mock: respx.M
@pytest.mark.parametrize("status", [401, 403, 429, 503])
def test_upstream_http_errors_keep_status(respx_mock: respx.MockRouter, status: int) -> None:
respx_mock.post(f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web").respond(
respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond(
status_code=status, json={"error": {"message": "upstream failure"}}, headers={"Retry-After": "2"}
)
with pytest.raises(openai.APIError, match="upstream failure") as error:
@ -220,3 +234,48 @@ def test_explicit_key_wins_and_headers_are_not_mutated(monkeypatch: pytest.Monke
def test_missing_key_fails_before_network() -> None:
with pytest.raises(ValueError, match="WEBIQ_API_KEY"):
WebIQSearchConfig().validate_environment({})
@pytest.mark.parametrize(
"result_metadata, response_metadata",
[
({"snippet": "upstream", "date": "upstream", "last_updated": "upstream"}, {}),
({}, {"results": "upstream", "object": "upstream"}),
],
)
def test_metadata_cannot_replace_standard_search_fields(
respx_mock: respx.MockRouter, result_metadata: dict[str, str], response_metadata: dict[str, str]
) -> None:
respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond(
json={
"webResults": [
{
"title": "Title",
"url": "https://example.com",
"content": "Passage",
"lastUpdatedAt": "2026-01-02T00:00:00Z",
"language": "en",
**result_metadata,
}
],
"traceId": "trace-1",
**response_metadata,
}
)
response: Final = litellm.search(query="query", search_provider="webiq", api_key="key")
assert response.model_dump() == {
"object": "search",
"results": [
{
"title": "Title",
"url": "https://example.com",
"snippet": "Passage",
"date": "2026-01-02T00:00:00Z",
"last_updated": "2026-01-02T00:00:00Z",
"language": "en",
}
],
"traceId": "trace-1",
}