FEATURED · 精选文章

@langchain/mistralai 集成实战:在 LangChain.js 中接入 Mistral 聊天模型、嵌入与代码补全

发布时间 / 2026/9/13 11:53:03
来源 / 创域科博编辑部
栏目 / 资讯中心
@langchain/mistralai 集成实战:在 LangChain.js 中接入 Mistral 聊天模型、嵌入与代码补全 langchain/mistralai 集成实战在 LangChain.js 中接入 Mistral 聊天模型、嵌入与代码补全【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs本指南以langchain/mistralai官方 README 为核心系统讲解如何在 LangChain.js 项目中安装并接入 Mistral 系列模型通过ChatMistralAI完成对话与流式输出、借助MistralAIEmbeddings生成文本向量、并利用MistralAI实现以 Codestral 为代表的代码补全FIM能力。读完本文你将掌握完整的环境配置、构造参数含义、工具调用与结构化输出等进阶用法并了解该包在开源仓库langchainjs中的源码实现细节。一、包定位与安装langchain/mistralai是 LangChain.js 针对 Mistral 官方 SDKmistralai/mistralai的集成包。在仓库中它位于 libs/providers/langchain-mistralai包内导出三个核心类见 src/index.tsChatMistralAI推荐使用的聊天模型集成封装 Mistral 系列对话模型MistralAIEmbeddingsMistral 嵌入模型集成MistralAI面向代码补全场景的 LLM 集成默认对接 Codestral 模型。1.1 安装命令在任意 Node.js20项目中执行npm install langchain/mistralai langchain/core该包在 package.json 中声明mistralai/mistralai: 2.2.1为直接依赖langchain/core: ^1.0.0为 peerDependencypeer 依赖版本以仓库当前声明为准README 中的^0.3.0示例为早期模板写法。1.2 统一 langchain/core 实例LangChain 生态由多个包组成如果langchain/mistralai与项目中的其他 LangChain 包各自解析到不同版本的langchain/core可能出现类型不兼容或运行时行为异常。官方推荐在项目package.json中显式锁定版本README 给出的完整模板如下{ name: your-project, version: 0.0.0, dependencies: { langchain/core: ^0.3.0, langchain/mistralai: ^0.0.0 }, resolutions: { langchain/core: ^0.3.0 }, overrides: { langchain/core: ^0.3.0 }, pnpm: { overrides: { langchain/core: ^0.3.0 } } }其中resolutionsyarn、overridesnpm、pnpm.overridespnpm分别对应不同包管理器建议同时声明以最大化兼容性。实际使用时应将版本号替换为你安装的langchain/core版本并与 langchainjs 仓库的 package.json 中 pnpm workspace 锁定的版本保持一致。1.3 配置 API Key聊天、嵌入、LLM 三个类均支持两种方式提供密钥构造参数apiKey或环境变量MISTRAL_API_KEY。若两者均缺失构造函数会直接抛出异常源码见 chat_models.ts、embeddings.tsexport MISTRAL_API_KEYyour-api-key二、ChatMistralAI聊天模型接入ChatMistralAI是官方推荐的 Mistral 模型交互入口继承BaseChatModel默认模型为mistral-small-latest。2.1 最小可运行示例import { ChatMistralAI } from langchain/mistralai; import { HumanMessage } from langchain/core/messages; const model new ChatMistralAI({ apiKey: process.env.MISTRAL_API_KEY, modelName: mistral-small, }); const response await model.invoke(new HumanMessage(Hello world!));invoke返回标准AIMessage对象包含content、response_metadata、tool_calls、usage_metadata等字段。2.2 构造参数详解源码中ChatMistralAIInput接口chat_models.ts定义了以下核心参数参数类型/默认值说明apiKey默认读MISTRAL_API_KEYMistral API 密钥modelmistral-small-latest模型名称推荐写法modelName同model旧版别名已标记deprecatedtemperature0.7范围 0.0~2.0采样温度越高输出越随机topP1范围 0~1核采样仅考虑概率质量占比 topP 的 tokenmaxTokens无默认最大生成 token 数promptmaxTokens 不能超过模型上下文长度streamingfalse是否流式返回safePromptfalse是否在对话前注入安全提示词safeMode为旧别名seed/randomSeed无默认随机采样种子设置后多次调用可复现presencePenalty无默认存在惩罚值越高词汇越多样frequencyPenalty无默认频率惩罚抑制已高频出现词汇的重复numCompletions无默认每次请求返回的补全数量输入 token 只计费一次streamUsagetrue流式响应中是否携带 token 用量serverURL无默认覆盖 Mistral SDK 默认服务地址endpoint为旧别名beforeRequestHooks/requestErrorHooks/responseHooks无默认请求生命周期钩子httpClient无默认自定义 HTTP 客户端可定制 fetch 实现所有字段默认值均可在 chat_models.ts 的类属性声明与构造函数赋值逻辑L973-L1015中得到验证。2.3 流式输出ChatMistralAI重写了基类的流式链路内部通过client.chat.stream({ ...input, stream: true })调用 Mistral SDKchat_models.ts并将每个增量块转换为AIMessageChunkimport { ChatMistralAI } from langchain/mistralai; const model new ChatMistralAI({ apiKey: process.env.MISTRAL_API_KEY, modelName: mistral-small, }); const stream await model.stream(new HumanMessage(Hello world!)); for await (const chunk of stream) { console.log(chunk); }每个 chunk 只包含增量片段若需聚合为完整消息可用concat工具函数累积合并。流式场景下默认输出 token 用量streamUsage为 true最终块的usage_metadata会携带input_tokens/output_tokens/total_tokens。2.4 工具调用bindToolsChatMistralAI通过bindTools将 LangChain 工具转换为 Mistral 格式chat_models.ts。LangChain 工具如 zod schema 描述的structuredTool会被转换为{ type: function, function: { name, description, parameters } }zod schema 自动序列化为 JSON SchematoJsonSchema见 _convertToolToMistralToolimport { z } from zod; const GetWeather { name: GetWeather, description: Get the current weather in a given location, schema: z.object({ location: z.string().describe(The city and state, e.g. San Francisco, CA), }), }; const modelWithTools model.bindTools([GetWeather], { tool_choice: auto }); const aiMsg await modelWithTools.invoke( Which city is hotter today: LA or NY? ); console.log(aiMsg.tool_calls); // [{ name, args, type, id }, ...]调用选项如tool_choice、response_format也可通过.invoke第二参数或.withConfig传入。2.5 结构化输出配合withStructuredOutput可直接获得符合 zod schema 的 JSON 对象import { z } from zod; const Joke z.object({ setup: z.string().describe(The setup of the joke), punchline: z.string().describe(The punchline to the joke), rating: z.number().optional().describe(How funny the joke is, from 1 to 10), }).describe(Joke to tell user.); const structuredLlm model.withStructuredOutput(Joke, { name: Joke }); const jokeResult await structuredLlm.invoke(Tell me a joke about cats); // { setup: ..., punchline: ..., rating: 7 }2.6 Token 用量统计非流式与流式调用均可在结果上读取用量元数据const aiMsg await model.invoke(Hello world!); console.log(aiMsg.usage_metadata); // { input_tokens: 13, output_tokens: 89, total_tokens: 102 }三、底层消息转换机制ChatMistralAI与 Mistral API 之间的消息桥接由 convertMessagesToMistralMessages 完成角色映射规则为human → user、ai → assistant、system → system、tool → tool、function → assistant。值得注意的细节多模态内容复杂消息内容仅支持text与image_url两种 chunk 类型且image_url仅允许出现在user/assistant角色中其余类型会抛出明确错误chat_models.ts工具调用一致性构建请求前会收集所有 tool 响应 ID过滤掉没有对应响应的助手工具调用确保 assistant toolCalls 与 tool 响应一一对应chat_models.ts流式增量转换工具调用增量会补上index字段并映射为tool_call_chunks流式 token 用量的处理逻辑见 _convertDeltaToMessageChunk。四、MistralAIEmbeddings嵌入模型包内通过MistralAIEmbeddings支持 Mistral 嵌入模型默认模型为mistral-embed。4.1 基本用法import { MistralAIEmbeddings } from langchain/mistralai; const embeddings new MistralAIEmbeddings({ apiKey: process.env.MISTRAL_API_KEY, }); // 单条文本 const queryEmbedding await embeddings.embedQuery(Hello world); // 批量文本 const docEmbeddings await embeddings.embedDocuments([ Hello world, Bye bye, ]);4.2 参数与实现要点MistralAIEmbeddingsParamsembeddings.ts中的关键参数参数默认值说明model/modelNamemistral-embed嵌入模型名encodingFormatfloat输出向量格式batchSize512单次请求最多处理的文档数stripNewLinestrue是否将文本中的换行替换为空格官方推荐可能不适合部分场景serverURL无默认覆盖 SDK 默认服务地址实现层面embeddings.tsembedDocuments先按batchSize对输入分块chunkArray并发发出多个批次请求再按原始顺序拼接结果embedQuery单条调用二者都返回number[]请求通过AsyncCaller包装自动具备重试能力。五、MistralAI面向代码补全的 LLMFIM除了聊天与嵌入包内还提供继承LLM的MistralAI类llms.ts默认模型为codestral-latest主要面向代码补全场景。5.1 Fill-In-Middle 支持MistralAI通过useFim参数控制调用方式useFim: true走 Mistral SDK 的client.fim.complete()/client.fim.stream()接口支持 prompt suffix 的代码中段补全useFim: false退回client.chat.complete()/client.chat.stream()将 prompt 包装为 user 消息。默认值由模型名自动推断名称包含codestral时默认true否则为false见 isCodestralModel 与构造函数 L201-L202。5.2 参数与调用选项MistralAIInput除复用temperature默认 0、topP、maxTokens、randomSeed、streaming等参数外还新增suffix调用选项可选后缀文本配合 prompt 让模型填充二者之间的内容不提供时模型执行普通前缀补全batchSize默认20批量生成时按此大小分批useFim是否启用 FIM 接口。import { MistralAI } from langchain/mistralai; const llm new MistralAI({ apiKey: process.env.MISTRAL_API_KEY, model: codestral-latest, }); // 前缀补全 const completion await llm.invoke(def fibonacci(n):); // FIM 中段补全model 会根据前后文填充中间代码 const fimResult await llm.invoke(def foo():, { suffix: return result, });MistralAI的_generate实现会按batchSize分批并发并在streaming: true时逐 token 触发handleLLMNewToken回调llms.ts。六、请求钩子与自定义 HTTP 客户端三个类均支持通过beforeRequestHooks、requestErrorHooks、responseHooks干预请求生命周期钩子函数签名分别为beforeRequest: (req: Request) AwaitableRequest | void可在请求发出前改写请求如注入鉴权头requestError: (err: unknown, req: Request) Awaitablevoid请求出错时回调response: (res: Response, req: Request) Awaitablevoid收到响应时回调。内部实现embeddings.ts 可作参考会在未提供httpClient但声明了钩子时自动创建HTTPClient并在实例构造时统一注册钩子。httpClient参数则允许完全接管请求层例如替换 fetch 实现或接入自有代理。七、包的开发与测试README 的 Development 章节面向希望二次开发本包的贡献者以下命令在仓库根目录执行7.1 安装依赖与构建pnpm install构建当前包pnpm build --filter langchain/mistralai或进入 libs/providers/langchain-mistralai 目录后直接pnpm build。构建工具为 tsdown产物按 package.json 的exports字段同时输出 ESMdist/index.js与 CJSdist/index.cjs入口及对应类型声明。7.2 测试规范测试文件位于src/tests/下命名约定单元测试以.test.ts结尾例如 chat_models.test.ts集成测试以.int.test.ts结尾需要真实 API Key例如 chat_models.int.test.ts、embeddings.int.test.ts另有基于langchain/standard-tests的标准行为测试与流事件测试chat_models_stream_events.test.ts。运行方式pnpm test # 单元测试vitest run pnpm test:int # 集成测试vitest run --mode int7.3 代码质量与新增入口pnpm lint pnpm format若在src/下新增需要对外暴露的模块有两种方式将其导入并从 src/index.ts 再导出或在 package.json 的exports字段登记新入口随后执行pnpm build生成对应产物。八、小结langchain/mistralai为 LangChain.js 提供了对 Mistral 模型家族的一站式接入ChatMistralAI覆盖对话、流式、工具调用与结构化输出MistralAIEmbeddings提供批量向量化能力MistralAI则针对 Codestral 模型实现 Fill-In-Middle 代码补全。本文涉及的源码均可直接在该仓库 libs/providers/langchain-mistralai 目录下查阅结合 单元测试 与 流事件转换工具 可以进一步深入理解其内部行为。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
RELATED — 相关阅读

相关资讯

LATEST — 最新资讯

最新发布

TODAY — 本日精选

新闻

WEEKLY — 本周精选

新闻

MONTHLY — 本月精选

新闻