使用 mistral.rs 的 HTTP API 实现 Chat Completions 网页搜索web_search_options 完整实战指南【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本篇指南讲解如何在 mistral.rs 中以 OpenAI 兼容的 HTTP API 为 Chat Completions 请求启用内建网页搜索能力只需在服务端以--agent模式启动一个支持搜索工具的服务器然后在客户端请求体中传入web_search_options{}模型即可自主联网检索、抓取网页内容并基于实时信息作答。读完本文你将掌握启动命令、完整的 Python 调用代码、web_search_options的全部可配置字段以及搜索工具在服务端底层的真实执行机制。概述一条web_search_options引发的联网推理mistral.rs 对 OpenAI 的web_search_options请求字段提供了服务端原生支持。该功能不需要你在客户端自行实现搜索→工具调用→回传结果的多轮循环而是由服务端内置的 Agent 工具循环自动完成模型按需调用预置的网页搜索工具与网页内容提取工具检索结果被重新注入上下文后继续生成最终直接返回一段引用了实时信息的最终回答。对应到当前仓库该能力由三部分协同构成mistralrs-server-core/src/chat_completion.rs解析并归一化请求中的web_search_options与tools一起转换为服务端内部工具配置mistralrs-core/src/search/mod.rs定义搜索/提取工具的提示词描述、参数 Schema 与真实执行逻辑mistralrs-cli/src/args/mod.rs提供--agent、--enable-search、--search-embedding-model等命令行开关。第一步以 Agent 模式启动搜索服务器原文档给出的启动命令是mistralrs serve --agent -p 1234 -m Qwen/Qwen3-4B参数拆解如下参数作用serve启动 OpenAI 兼容的 HTTP 服务器--agent构建本地 Agent同时启用网页搜索、Python 代码执行与 Shell 执行并运行 Agent 工具循环--agentic是其别名-p 1234服务监听端口客户端将访问http://localhost:1234/v1/-m Qwen/Qwen3-4B指定 HuggingFace 模型仓库标识此处使用 Qwen3-4B需要说明的是--agent是一个全家桶开关。从 mistralrs-cli/src/commands/serve.rs 的源码可以看到传入--agent后服务端会自动把enable_search置为true。因此如果你只想启用网页搜索、不希望附带代码执行等能力可以显式使用更精确的组合# 仅启用网页搜索需搭配 embedding 重排序模型 mistralrs serve --enable-search -p 1234 -m Qwen/Qwen3-4B其中--enable-search启用与 OpenAIweb_search_options兼容的搜索能力会加载一个搜索 embedding 重排序模型默认是 EmbeddingGemma--search-embedding-model指定要加载的内建搜索 embedding 模型该参数要求同时传入--enable-search或--agent否则 CLI 会直接报错见 mistralrs-cli/src/commands/serve.rs。从服务端构建器的源码mistralrs-server-core/src/mistralrs_for_server_builder.rs看enable_search负责加载搜索重排序模型search_embedding_model用于覆盖默认的 EmbeddingGemma而search_callback则允许以编程方式完全替换内置的搜索实现——这些都是高级自定义入口默认情况下无需改动。第二步运行示例脚本服务启动后在仓库根目录执行python examples/server/web_search.py脚本的完整源码位于 examples/server/web_search.py。下面逐段解析其工作方式。构造 OpenAI 兼容客户端from openai import OpenAI client OpenAI(api_keyfoobar, base_urlhttp://localhost:1234/v1/)base_url指向 mistral.rs 服务器的/v1/端点api_key只是占位符mistral.rs 本地服务不做鉴权可以填写任意字符串。发起带网页搜索的请求messages [ { role: user, content: Can you show me some code using mistral.rs for running Llama 3.2 Vision?, } ] completion client.chat.completions.create( modeldefault, messagesmessages, tool_choiceauto, max_tokens1024, web_search_options{}, )这里的关键参数是web_search_options{}传{}表示启用网页搜索且全部选项走默认值tool_choiceauto允许模型自主决定是否调用搜索工具max_tokens1024限制单次生成的最大 token 数服务端在请求归一化阶段会把web_search_options与tools统一转换为内部工具配置见 mistralrs-server-core/src/chat_completion.rs随后交给 Agent 工具循环执行。读取结果# print(completion.usage) print(completion.choices[0].message.content) if completion.choices[0].message.tool_calls is not None: # Should never happen. tool_called completion.choices[0].message.tool_calls[0].function print(tool_called)正常路径下模型完成联网检索后会把最终答案写入choices[0].message.content直接打印即可示例中tool_calls的分支仅为防御性代码由于web_search_options模式下搜索由服务端内部完成客户端最终收到的应当是纯文本回答因此理论上不应出现未消费的工具调用如确实出现说明发生了异常情况可借此排查被注释掉的completion.usage行可取消注释用于观察本次请求的 token 用量统计。第三步web_search_options的完整参数说明虽然示例只传了{}但该字段支持丰富的配置项其数据结构定义于 mistralrs-core/src/request.rs。下表整理自该结构体字段类型说明search_context_sizeSearchContextSize控制注入上下文的搜索结果规模user_locationWebSearchUserLocation用户地理位置信息影响搜索结果的本地化filtersWebSearchFilters域名过滤allowed_domains仅允许与blocked_domains排除值为域名字符串列表external_web_accessbool是否允许外部网络访问return_token_budgetWebSearchReturnTokenBudget搜索结果回传的 token 预算枚举值为default/unlimitedsearch_content_typesVecWebSearchContentType搜索内容类型枚举值为text/imageimage_settingsWebSearchImageSettings图片搜索设置max_results最大结果数与caption是否生成说明search_descriptionString覆盖搜索工具默认的提示词描述extract_descriptionString覆盖网页提取工具默认的提示词描述地理位置示例user_location采用type: approximate的序列化格式见 mistralrs-core/src/request.rs支持city、region、country、timezone四个可选维度。一个带本地化搜索的完整请求示例如下completion client.chat.completions.create( modeldefault, messagesmessages, tool_choiceauto, max_tokens1024, web_search_options{ user_location: { type: approximate, approximate: { city: Shanghai, country: CN, region: CN-31, timezone: Asia/Shanghai, }, }, return_token_budget: default, filters: { allowed_domains: [arxiv.org, github.com], }, }, )服务端在构造搜索工具时会把上述地理位置拼接到搜索工具的描述文本中如The users location is: Shanghai, CN-31, CN, Asia/Shanghai.从而引导模型给出本地化更强的查询词——该逻辑见 mistralrs-core/src/search/mod.rs。底层原理搜索工具与执行流程启用web_search_options后服务端会注册两个内建工具工具名定义于 mistralrs-core/src/search/mod.rs工具名输入参数职责mistralrs_search_the_webquery字符串根据查询词执行网页搜索返回标题、摘要、URL 与正文内容mistralrs_website_content_extractorurl字符串提取指定 URL 的网页正文内容二者的工具描述、参数 JSON Schema 由get_search_tools动态生成见 mistralrs-core/src/search/mod.rs并且均声明为strict: true的 Function 工具。搜索执行的真实路径以mistralrs_search_the_web为例mistralrs-core/src/search/mod.rs一次搜索的完整链路是URL 直取若模型传入的查询词本身是http://或https://开头的 URL则直接抓取该页面并把正文作为唯一结果返回因为 DuckDuckGo 对裸 URL 的搜索返回为空搜索引擎查询否则请求https://html.duckduckgo.com/html/?q编码后的查询词使用形如mistralrs/版本号 (OS; ARCH; FAMILY)的 User-Agent解析结果页用scraper解析 DuckDuckGo HTML 结果通过.result、.result__title、.result__snippet、.result__url四个 CSS 选择器提取标题、摘要与链接过滤掉任一字段为空的结果最多保留MAX_SEARCH_RESULTS 10条并发抓取正文对每条结果并发发起页面抓取并用html2text把 HTML 转换为纯文本后填充content字段返回结构化结果最终把SearchResulttitle/description/url/content列表回传给模型模型据此继续生成带引用的回答。mistralrs_website_content_extractor则更简单直接抓取给定 URL将 HTML 转为纯文本返回抓取失败时返回ERROR: failed to extract content占位文本见 mistralrs-core/src/search/mod.rs。两个工具共用的网络参数位于文件顶部的常量连接超时 5 秒SEARCH_CONNECT_TIMEOUT、请求超时 10 秒SEARCH_REQUEST_TIMEOUT、最大结果数 10MAX_SEARCH_RESULTS见 mistralrs-core/src/search/mod.rs。工具描述即提示词值得注意的一个设计细节是搜索/提取工具的英文描述本身就是精心编写的提示词。例如搜索工具描述中明确要求模型如果用户需要最新信息就调用此工具调用后必须基于输出完成回答输入应是查询词而非 URL并给出了期望的 JSON 输出结构sources与output数组。这些描述SEARCH_DESCRIPTION、EXTRACT_DESCRIPTION会被注入模型可见的工具定义中直接影响模型的调用决策质量。与普通 Tool Calling 的区别及 API 兼容性如果你已经熟悉 examples/server/tool_calling.py 展示的客户端侧工具调用模式可以这样对比理解普通 tool calling客户端循环客户端在tools中自行声明函数 Schema模型返回tool_calls后由客户端执行函数、再把结果以role: tool的消息回传需要客户端维护多轮对话web_search_options服务端 Agent 循环搜索工具由服务端注册检索与回传全部在服务端完成客户端只需传web_search_options{}最终直接拿到文本回答。此外需要特别留意 API 差异在 Chat Completions 接口中应使用web_search_options字段而tools[].typeweb_search这种工具声明形式只被 Responses API 支持如果在 Chat Completions 中使用会触发明确的报错提示tools[].typeweb_searchis only supported by the Responses API; useweb_search_optionswith Chat Completions见 mistralrs-server-core/src/openai.rs。这一点在 mistralrs-server-core/src/openai.rs 的单元测试中也有对应断言。实践要点与注意事项网络可达性搜索功能依赖对html.duckduckgo.com及目标网站的实时访问服务器所在环境需要具备出网能力默认值即可用web_search_options{}是最低成本的启用方式全部选项取默认值按需再叠加user_location、filters、return_token_budget等精细化配置域名过滤filters.allowed_domains/blocked_domains用于限定搜索与提取的域名范围适合对检索来源有合规要求的场景注意域名列表存在数量上限校验见 mistralrs-server-core/src/openai.rs模型选择--agent/--enable-search会加载搜索 embedding 重排序模型首次启动需要下载对应权重主模型建议选择工具调用能力较强的型号如 Qwen3 系列以获得更稳定的搜索决策结果上限单次搜索最多返回 10 条结果且每条正文内容会在后续处理中按 token 预算截断SearchResult::cap_content_len见 mistralrs-core/src/search/mod.rs因此大文档页面只会保留前缀内容。延伸阅读服务端 Agent 循环与多工具调度examples/server/agentic_tool_rounds.py、examples/server/tool_dispatch.py客户端侧手工工具调用范式examples/server/tool_calling.py搜索/提取工具的 Rust 实现mistralrs-core/src/search/mod.rsweb_search_options数据结构定义mistralrs-core/src/request.rsCLI 参数--agent/--enable-search/--search-embedding-modelmistralrs-cli/src/args/mod.rs【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 mistral.rs 的 HTTP API 实现 Chat Completions 网页搜索（web_search_options 完整实战指南）
使用 mistral.rs 的 HTTP API 实现 Chat Completions 网页搜索web_search_options 完整实战指南【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本篇指南讲解如何在 mistral.rs 中以 OpenAI 兼容的 HTTP API 为 Chat Completions 请求启用内建网页搜索能力只需在服务端以--agent模式启动一个支持搜索工具的服务器然后在客户端请求体中传入web_search_options{}模型即可自主联网检索、抓取网页内容并基于实时信息作答。读完本文你将掌握启动命令、完整的 Python 调用代码、web_search_options的全部可配置字段以及搜索工具在服务端底层的真实执行机制。概述一条web_search_options引发的联网推理mistral.rs 对 OpenAI 的web_search_options请求字段提供了服务端原生支持。该功能不需要你在客户端自行实现搜索→工具调用→回传结果的多轮循环而是由服务端内置的 Agent 工具循环自动完成模型按需调用预置的网页搜索工具与网页内容提取工具检索结果被重新注入上下文后继续生成最终直接返回一段引用了实时信息的最终回答。对应到当前仓库该能力由三部分协同构成mistralrs-server-core/src/chat_completion.rs解析并归一化请求中的web_search_options与tools一起转换为服务端内部工具配置mistralrs-core/src/search/mod.rs定义搜索/提取工具的提示词描述、参数 Schema 与真实执行逻辑mistralrs-cli/src/args/mod.rs提供--agent、--enable-search、--search-embedding-model等命令行开关。第一步以 Agent 模式启动搜索服务器原文档给出的启动命令是mistralrs serve --agent -p 1234 -m Qwen/Qwen3-4B参数拆解如下参数作用serve启动 OpenAI 兼容的 HTTP 服务器--agent构建本地 Agent同时启用网页搜索、Python 代码执行与 Shell 执行并运行 Agent 工具循环--agentic是其别名-p 1234服务监听端口客户端将访问http://localhost:1234/v1/-m Qwen/Qwen3-4B指定 HuggingFace 模型仓库标识此处使用 Qwen3-4B需要说明的是--agent是一个全家桶开关。从 mistralrs-cli/src/commands/serve.rs 的源码可以看到传入--agent后服务端会自动把enable_search置为true。因此如果你只想启用网页搜索、不希望附带代码执行等能力可以显式使用更精确的组合# 仅启用网页搜索需搭配 embedding 重排序模型 mistralrs serve --enable-search -p 1234 -m Qwen/Qwen3-4B其中--enable-search启用与 OpenAIweb_search_options兼容的搜索能力会加载一个搜索 embedding 重排序模型默认是 EmbeddingGemma--search-embedding-model指定要加载的内建搜索 embedding 模型该参数要求同时传入--enable-search或--agent否则 CLI 会直接报错见 mistralrs-cli/src/commands/serve.rs。从服务端构建器的源码mistralrs-server-core/src/mistralrs_for_server_builder.rs看enable_search负责加载搜索重排序模型search_embedding_model用于覆盖默认的 EmbeddingGemma而search_callback则允许以编程方式完全替换内置的搜索实现——这些都是高级自定义入口默认情况下无需改动。第二步运行示例脚本服务启动后在仓库根目录执行python examples/server/web_search.py脚本的完整源码位于 examples/server/web_search.py。下面逐段解析其工作方式。构造 OpenAI 兼容客户端from openai import OpenAI client OpenAI(api_keyfoobar, base_urlhttp://localhost:1234/v1/)base_url指向 mistral.rs 服务器的/v1/端点api_key只是占位符mistral.rs 本地服务不做鉴权可以填写任意字符串。发起带网页搜索的请求messages [ { role: user, content: Can you show me some code using mistral.rs for running Llama 3.2 Vision?, } ] completion client.chat.completions.create( modeldefault, messagesmessages, tool_choiceauto, max_tokens1024, web_search_options{}, )这里的关键参数是web_search_options{}传{}表示启用网页搜索且全部选项走默认值tool_choiceauto允许模型自主决定是否调用搜索工具max_tokens1024限制单次生成的最大 token 数服务端在请求归一化阶段会把web_search_options与tools统一转换为内部工具配置见 mistralrs-server-core/src/chat_completion.rs随后交给 Agent 工具循环执行。读取结果# print(completion.usage) print(completion.choices[0].message.content) if completion.choices[0].message.tool_calls is not None: # Should never happen. tool_called completion.choices[0].message.tool_calls[0].function print(tool_called)正常路径下模型完成联网检索后会把最终答案写入choices[0].message.content直接打印即可示例中tool_calls的分支仅为防御性代码由于web_search_options模式下搜索由服务端内部完成客户端最终收到的应当是纯文本回答因此理论上不应出现未消费的工具调用如确实出现说明发生了异常情况可借此排查被注释掉的completion.usage行可取消注释用于观察本次请求的 token 用量统计。第三步web_search_options的完整参数说明虽然示例只传了{}但该字段支持丰富的配置项其数据结构定义于 mistralrs-core/src/request.rs。下表整理自该结构体字段类型说明search_context_sizeSearchContextSize控制注入上下文的搜索结果规模user_locationWebSearchUserLocation用户地理位置信息影响搜索结果的本地化filtersWebSearchFilters域名过滤allowed_domains仅允许与blocked_domains排除值为域名字符串列表external_web_accessbool是否允许外部网络访问return_token_budgetWebSearchReturnTokenBudget搜索结果回传的 token 预算枚举值为default/unlimitedsearch_content_typesVecWebSearchContentType搜索内容类型枚举值为text/imageimage_settingsWebSearchImageSettings图片搜索设置max_results最大结果数与caption是否生成说明search_descriptionString覆盖搜索工具默认的提示词描述extract_descriptionString覆盖网页提取工具默认的提示词描述地理位置示例user_location采用type: approximate的序列化格式见 mistralrs-core/src/request.rs支持city、region、country、timezone四个可选维度。一个带本地化搜索的完整请求示例如下completion client.chat.completions.create( modeldefault, messagesmessages, tool_choiceauto, max_tokens1024, web_search_options{ user_location: { type: approximate, approximate: { city: Shanghai, country: CN, region: CN-31, timezone: Asia/Shanghai, }, }, return_token_budget: default, filters: { allowed_domains: [arxiv.org, github.com], }, }, )服务端在构造搜索工具时会把上述地理位置拼接到搜索工具的描述文本中如The users location is: Shanghai, CN-31, CN, Asia/Shanghai.从而引导模型给出本地化更强的查询词——该逻辑见 mistralrs-core/src/search/mod.rs。底层原理搜索工具与执行流程启用web_search_options后服务端会注册两个内建工具工具名定义于 mistralrs-core/src/search/mod.rs工具名输入参数职责mistralrs_search_the_webquery字符串根据查询词执行网页搜索返回标题、摘要、URL 与正文内容mistralrs_website_content_extractorurl字符串提取指定 URL 的网页正文内容二者的工具描述、参数 JSON Schema 由get_search_tools动态生成见 mistralrs-core/src/search/mod.rs并且均声明为strict: true的 Function 工具。搜索执行的真实路径以mistralrs_search_the_web为例mistralrs-core/src/search/mod.rs一次搜索的完整链路是URL 直取若模型传入的查询词本身是http://或https://开头的 URL则直接抓取该页面并把正文作为唯一结果返回因为 DuckDuckGo 对裸 URL 的搜索返回为空搜索引擎查询否则请求https://html.duckduckgo.com/html/?q编码后的查询词使用形如mistralrs/版本号 (OS; ARCH; FAMILY)的 User-Agent解析结果页用scraper解析 DuckDuckGo HTML 结果通过.result、.result__title、.result__snippet、.result__url四个 CSS 选择器提取标题、摘要与链接过滤掉任一字段为空的结果最多保留MAX_SEARCH_RESULTS 10条并发抓取正文对每条结果并发发起页面抓取并用html2text把 HTML 转换为纯文本后填充content字段返回结构化结果最终把SearchResulttitle/description/url/content列表回传给模型模型据此继续生成带引用的回答。mistralrs_website_content_extractor则更简单直接抓取给定 URL将 HTML 转为纯文本返回抓取失败时返回ERROR: failed to extract content占位文本见 mistralrs-core/src/search/mod.rs。两个工具共用的网络参数位于文件顶部的常量连接超时 5 秒SEARCH_CONNECT_TIMEOUT、请求超时 10 秒SEARCH_REQUEST_TIMEOUT、最大结果数 10MAX_SEARCH_RESULTS见 mistralrs-core/src/search/mod.rs。工具描述即提示词值得注意的一个设计细节是搜索/提取工具的英文描述本身就是精心编写的提示词。例如搜索工具描述中明确要求模型如果用户需要最新信息就调用此工具调用后必须基于输出完成回答输入应是查询词而非 URL并给出了期望的 JSON 输出结构sources与output数组。这些描述SEARCH_DESCRIPTION、EXTRACT_DESCRIPTION会被注入模型可见的工具定义中直接影响模型的调用决策质量。与普通 Tool Calling 的区别及 API 兼容性如果你已经熟悉 examples/server/tool_calling.py 展示的客户端侧工具调用模式可以这样对比理解普通 tool calling客户端循环客户端在tools中自行声明函数 Schema模型返回tool_calls后由客户端执行函数、再把结果以role: tool的消息回传需要客户端维护多轮对话web_search_options服务端 Agent 循环搜索工具由服务端注册检索与回传全部在服务端完成客户端只需传web_search_options{}最终直接拿到文本回答。此外需要特别留意 API 差异在 Chat Completions 接口中应使用web_search_options字段而tools[].typeweb_search这种工具声明形式只被 Responses API 支持如果在 Chat Completions 中使用会触发明确的报错提示tools[].typeweb_searchis only supported by the Responses API; useweb_search_optionswith Chat Completions见 mistralrs-server-core/src/openai.rs。这一点在 mistralrs-server-core/src/openai.rs 的单元测试中也有对应断言。实践要点与注意事项网络可达性搜索功能依赖对html.duckduckgo.com及目标网站的实时访问服务器所在环境需要具备出网能力默认值即可用web_search_options{}是最低成本的启用方式全部选项取默认值按需再叠加user_location、filters、return_token_budget等精细化配置域名过滤filters.allowed_domains/blocked_domains用于限定搜索与提取的域名范围适合对检索来源有合规要求的场景注意域名列表存在数量上限校验见 mistralrs-server-core/src/openai.rs模型选择--agent/--enable-search会加载搜索 embedding 重排序模型首次启动需要下载对应权重主模型建议选择工具调用能力较强的型号如 Qwen3 系列以获得更稳定的搜索决策结果上限单次搜索最多返回 10 条结果且每条正文内容会在后续处理中按 token 预算截断SearchResult::cap_content_len见 mistralrs-core/src/search/mod.rs因此大文档页面只会保留前缀内容。延伸阅读服务端 Agent 循环与多工具调度examples/server/agentic_tool_rounds.py、examples/server/tool_dispatch.py客户端侧手工工具调用范式examples/server/tool_calling.py搜索/提取工具的 Rust 实现mistralrs-core/src/search/mod.rsweb_search_options数据结构定义mistralrs-core/src/request.rsCLI 参数--agent/--enable-search/--search-embedding-modelmistralrs-cli/src/args/mod.rs【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考