mirror of
https://github.com/BerriAI/litellm.git
synced 2026-11-18 09:45:23 +00:00
fix(search): protect WebIQ result fields and simplify endpoint configuration
This commit is contained in:
parent
92d30bf16b
commit
30104f38ce
3 changed files with 86 additions and 94 deletions
|
|
@ -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
|
||||
|
|
@ -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
|
||||
}
|
||||
),
|
||||
)
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue