LangChain.js xAI 集成实战ChatXAI 聊天模型与 Live Search 实时搜索工具完全指南【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs本文以 LangChain.js 仓库中的langchain/xai集成包libs/providers/langchain-xai为核心系统讲解如何通过ChatXAI调用 xAI 的 Grok 系列模型并深入剖析其服务端工具Server Tool Calling机制——尤其是 Live Search 实时搜索的参数体系、数据源配置与覆盖优先级。读完本文你将掌握从环境配置、基础对话到多数据源实时检索、内置工具与自定义函数工具混用的完整实战方案并能理解底层请求参数如何被组装与发送。一、包概览与安装langchain/xai是 LangChain.js 生态中面向 xAI 平台的官方集成包为 Grok 系列模型提供聊天模型Chat Model推理能力并封装了 xAI 特有的服务端工具调用Server Tool Calling能力。包内核心导出由 src/index.ts 统一暴露ChatXAI系列聊天模型由chat_models模块导出tools命名空间由tools模块导出包含 xAI 内置工具工厂函数安装依赖npm install langchain/xai langchain/core环境前提根据 package.json 的engines字段该包要求 Node.js 20langchain/xai以langchain/openaiworkspace 内依赖为底层实现基础langchain/core^1.0.0作为 peer dependency。二、快速开始首个 ChatXAI 调用2.1 配置 API KeyxAI 的 API Key 可以通过环境变量注入也可以在构造函数中显式传入export XAI_API_KEYimport { ChatXAI } from langchain/xai; import { HumanMessage } from langchain/core/messages; const model new ChatXAI({ apiKey: process.env.XAI_API_KEY, // Default value. }); const message new HumanMessage(What color is the sky?); const res await model.invoke([message]);ChatXAI会优先读取构造函数传入的apiKey未传入时默认使用process.env.XAI_API_KEY即上面导出的环境变量。这一点与 LangChain.js 其他模型提供方如ChatOpenAI的环境变量读取约定保持一致。2.2 指定模型与流式输出虽然 README 的基础示例未显式指定模型名但实际使用中通常需要传入model参数例如 Grok 系列模型grok-3-fast。ChatXAI也支持 LangChain.js 标准的流式调用.stream、结构化输出.withStructuredOutput等能力因为其底层直接复用langchain/openai的ChatOpenAICompletions实现可参考 completions.ts 中的类定义。2.3 底层实现要点从源码看completions.tsChatXAI的请求参数类型扩展自 OpenAI 的ChatCompletionCreateParams额外加入了 xAI 专属字段search_parametersexport type ChatXAICompletionsInvocationParams Omit OpenAIClient.Chat.Completions.ChatCompletionCreateParams, messages { search_parameters?: XAISearchParametersPayload; };此外xAI 模型返回的额外信息如思维链内容reasoning_content会被放入消息的additional_kwargs中类型定义同样可在该文件确认。这意味着凡是 OpenAI 兼容的调用习惯tools、tool_choice、stream 等在ChatXAI上基本可以直接平移使用。三、Server Tool CallingLive Search 实时搜索3.1 什么是服务端工具xAI 支持服务端工具server-side tools这类工具由 xAI API 在服务端直接执行无需客户端自行实现工具逻辑或二次调用。内置的live_search工具可以让模型实时检索网页信息从而回答需要最新数据的问题如今天的科技新闻。3.2 使用内置 live_search 工具通过tools命名空间中的工厂函数xaiLiveSearch创建内置工具再通过bindTools绑定到模型import { ChatXAI, tools } from langchain/xai; const model new ChatXAI({ model: grok-3-fast, }); // Create the built-in live_search tool with optional parameters const searchTool tools.xaiLiveSearch({ maxSearchResults: 5, returnCitations: true, }); // Bind the live_search tool to the model const modelWithSearch model.bindTools([searchTool]); // The model will search the web for real-time information const result await modelWithSearch.invoke( What happened in tech news today? ); console.log(result.content);创建后的工具对象形如{ type: live_search_deprecated_20251215, name: live_search, ... }其类型常量XAI_LIVE_SEARCH_TOOL_TYPE与XAI_LIVE_SEARCH_TOOL_NAME定义于 tools/live_search.ts。⚠️ 兼容性提示根据源码中的类型注释live_search使用的是 xAI 已弃用的 Live Search API 形态xAI 已于 2025-12-15 弃用官方推荐迁移到新的 agentic 工具调用 API即下文 3.7 节的xaiWebSearch与xaiXSearch。README 中的示例仍然可用但新项目建议优先考虑新式工具。3.3 通过 searchParameters 获得更多控制除了绑定工具还可以在构造模型时直接配置searchParameters等效于设置请求中的search_parameters字段import { ChatXAI } from langchain/xai; const model new ChatXAI({ model: grok-3-fast, searchParameters: { mode: auto, // auto | on | off max_search_results: 5, from_date: 2024-01-01, // ISO date string return_citations: true, }, }); const result await model.invoke(What are the latest AI developments?);searchParameters的类型XAISearchParameters定义于 live_search.ts各字段语义如下字段类型默认值说明modeauto \| on \| offauto何时执行搜索auto由模型自行决定on每次都搜索off从不搜索max_search_resultsnumber20返回的最大搜索结果条数from_datestring无只包含该日期ISO 8601如2024-01-01之后的内容to_datestring无只包含该日期ISO 8601之前的内容return_citationsbooleantrue是否返回引用/来源信息sourcesXAISearchSource[]无指定使用的数据源web/news/x/rss省略时 xAI 默认启用 web、news 和 x 三类来源其中mode是必选字段由buildSearchParametersPayload在组装请求负载时兜底为auto详见 live_search.ts 的负载构建函数。3.4 按请求覆盖 searchParameters搜索参数可以做到一次配置、按需覆盖——在每次invoke时传入searchParameters即可临时覆盖实例级配置const result await model.invoke(Find recent news about SpaceX, { searchParameters: { mode: on, max_search_results: 10, sources: [ { type: web, allowed_websites: [spacex.com, nasa.gov], }, ], }, });3.5 配置数据源web / news / x / rss通过searchParameters.sources可以精细控制 Live Search 使用哪些数据源每种来源对应官方文档中的一种类型web、news、x、rssconst result await model.invoke( What are the latest updates from xAI and related news?, { searchParameters: { mode: on, sources: [ { type: web, // Only search on these websites allowed_websites: [x.ai], }, { type: news, // Exclude specific news websites excluded_websites: [bbc.co.uk], }, { type: x, // Focus on specific X handles included_x_handles: [xai], }, ], }, } );各来源的可用字段源码中XAISearchSource联合类型见 live_search.tswebcountryISO alpha-2 国家代码用于偏向某地区结果、allowed_websites仅检索这些站点最多 5 个、excluded_websites排除这些站点最多 5 个、safe_search安全搜索开关newscountry、excluded_websites最多 5 个、safe_searchxincluded_x_handles限定检索的 X 账号最多 10 个、excluded_x_handles排除的 X 账号最多 10 个、post_favorite_count帖子的最低点赞数、post_view_count帖子的最低浏览量rsslinksRSS 源地址列表也可以把 RSS 订阅源作为数据源让模型直接汇总某个 Feed 的最新内容const result await model.invoke(Summarize the latest posts from this feed, { searchParameters: { mode: on, sources: [ { type: rss, links: [https://example.com/feed.rss], }, ], }, });提示allowed_websites与excluded_websites不可同时用于同一来源allowed_x_handles与excluded_x_handles同理这是底层 API 的约束代码注释中已明确说明。3.6 camelCase 与 snake_case 的自动映射使用xaiLiveSearch工厂函数时TypeScript 侧的工具选项采用camelCase命名它们会被自动映射为底层 JSON APIsearch_parameters对象中的snake_case字段名TypeScriptcamelCaseAPIsnake_casemaxSearchResultsmax_search_resultsfromDatefrom_datetoDateto_datereturnCitationsreturn_citationsallowedWebsitesallowed_websitesexcludedWebsitesexcluded_websitesincludedXHandlesincluded_x_handles该映射在 tools/live_search.ts 的xaiLiveSearch工厂与mapToolSourceToSearchSource函数中逐一完成——源码对每个可选字段都做了! undefined判空未配置的字段不会出现在请求负载中。3.7 与自定义函数工具混用live_search内置工具可以与标准的 function calling 工具一起绑定实现实时搜索 业务函数调用的混合智能体import { ChatXAI, tools } from langchain/xai; const model new ChatXAI({ model: grok-3-fast }); const modelWithTools model.bindTools([ tools.xaiLiveSearch(), // Built-in server tool { // Custom function tool type: function, function: { name: get_stock_price, description: Get the current stock price, parameters: { type: object, properties: { symbol: { type: string }, }, required: [symbol], }, }, }, ]);底层实现发送请求前代码会用filterXAIBuiltInTools将live_search这类内置工具从标准tools数组中剔除因为内置工具是通过search_parameters字段控制的不能作为普通 function tool 上报而普通函数工具则被保留并正常发送。该过滤逻辑与相关工具类型集合XAI_BUILT_IN_TOOL_TYPES均位于 completions.ts并有对应的单测覆盖见 src/tests/live_search.test.ts。四、参数优先级tool instance call当工具定义、实例级searchParameters、单次调用覆盖同时存在时合并策略由 live_search.ts 中的mergeSearchParams决定优先级从低到高为工具级参数如xaiLiveSearch中配置的选项实例级默认参数new ChatXAI({ searchParameters })单次调用参数invoke(msg, { searchParameters })export function mergeSearchParams( instanceParams?: XAISearchParameters, callParams?: XAISearchParameters, toolParams?: XAISearchParameters ): XAISearchParameters | undefined { return { ...(toolParams ?? {}), ...(instanceParams ?? {}), ...(callParams ?? {}), }; }即高层级参数按字段粒度覆盖低层级参数、但不会清除低层级中未覆盖的字段。这一点在 src/tests/live_search.test.ts 中有完整测试用例验证例如实例级设置了mode: auto、调用级设置了mode: on时最终mode取on而实例级未被子级覆盖的return_citations: true仍然保留。同时buildSearchParametersPayload负责把高层参数对象转换为发送给 API 的最终负载mode缺省补auto其余字段仅在显式配置时才写入sources为空数组时不会发送。五、源码视角更新一代的 agentic 内置工具README 主推的live_search属于已弃用的 Live Search API 形态。从当前仓库源码看tools/index.tstools命名空间还导出了 4 个新式 agentic 工具工厂它们属于 xAI agentic tool calling API由服务端执行适合作为长期方案工厂函数工具类型用途关键选项camelCasetools.xaiWebSearch()web_search网页搜索与浏览支持图片理解allowedDomains/excludedDomains各最多 5 个互斥、enableImageUnderstandingtools.xaiXSearch()x_searchX原 Twitter关键词/语义/用户搜索与帖子串抓取allowedXHandles/excludedXHandles各最多 10 个互斥、fromDate/toDate、enableImageUnderstanding、enableVideoUnderstandingtools.xaiCodeExecution()code_interpreter服务端沙箱执行 Python预装 NumPy/Pandas/Matplotlib/SciPy用于计算、数据分析、财务建模无参数tools.xaiCollectionsSearch()file_search检索上传到 xAI Collections 的知识库文档适用于 RAG 与企业知识库问答vectorStoreIdscollection ID 列表例如源码中给出的迁移方式是把旧的xaiLiveSearch替换为两个更聚焦的工具// Old (deprecated): const searchTool tools.xaiLiveSearch({ maxSearchResults: 5 }); // New (recommended): const webSearch tools.xaiWebSearch({ allowedDomains: [example.com] }); const xSearch tools.xaiXSearch({ allowedXHandles: [elonmusk] });这些工厂函数的实现与逐字段 camelCase→snake_case 映射可分别在 tools/web_search.ts、tools/x_search.ts、tools/code_execution.ts、tools/collections_search.ts 中查看且每个工具都配有独立的单测目录tools/tests/。六、本地开发与测试在仓库中开发或调试langchain/xai包时官方流程如下6.1 安装依赖pnpm install6.2 构建包pnpm build或从仓库根目录按包过滤构建pnpm build --filter langchain/xai构建实际执行的是tsdown编译见 package.json 的build/build:compile脚本。6.3 运行测试测试文件应放在src/下的tests/目录中。单元测试以.test.ts结尾集成测试以.int.test.ts结尾$ pnpm test $ pnpm test:int仓库内测试覆盖相当完整例如 src/tests/live_search.test.ts 覆盖了参数合并优先级、负载构建与内置工具过滤chat_models/tests/下还有completions、responses、结构化输出、流式事件等测试tools/tests/下则为每个内置工具live_search、web_search、x_search、code_execution、collections_search提供了独立的测试文件。6.4 代码规范提交代码前运行 lint 与格式化pnpm lint pnpm format6.5 新增导出入口如果新增了需要导出的文件有两种方式在 src/index.ts 中import并重新export将其加入 package.json 的exports字段然后运行pnpm build生成新的入口文件。七、小结langchain/xai提供了一条从基础对话到实时信息检索的完整链路ChatXAI负责与 Grok 系列模型对话tools.xaiLiveSearch/searchParameters负责让模型获取实时网页信息sources支持 web、news、x、rss 四类数据源的精调而tool instance call的参数优先级让默认配置 按需覆盖成为可能。对于需要长期维护的新项目建议关注源码中已提供的xaiWebSearch、xaiXSearch、xaiCodeExecution、xaiCollectionsSearch新一代 agentic 工具它们代表了 xAI 服务端工具能力的演进方向。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考