Elixir LangChain

Elixir LangChain 使 Elixir 应用程序能够将 AI 服务和自托管模型（self-hosted models）集成到应用中。

当前支持的 AI 服务：

模型	v0.3.x	v0.5.x
OpenAI ChatGPT	✓	✓
OpenAI DALL-e 2（图像生成）	✓	?
Anthropic Claude	✓	✓
Anthropic Claude（思考模式）	X	✓
xAI Grok	X	✓
Google Gemini	✓	✓
Google Vertex AI*	✓	X
Ollama	✓	?
Mistral	✓	X
Bumblebee 自托管模型**	✓	?
LMStudio***	✓	?
Perplexity	✓	✓

• *Google Vertex AI 是 Google 的企业级产品
• **Bumblebee 自托管模型 - 包括 Llama、Mistral 和 Zephyr
• ***LMStudio 通过其 OpenAI 兼容 API（应用程序接口）
• ****xAI Grok 模型，包括 Grok-4、Grok-3-mini、Grok-4 Heavy（多代理）

LangChain 是 Language Chain 的缩写。LLM（大型语言模型，Large Language Model）是其中的"Language"部分。该库使 Elixir 应用程序更容易将不同的流程、集成、库、服务或功能与 LLM“链”接或连接在一起。

LangChain 是一个用于开发由语言模型驱动的应用程序的框架。它使应用程序具备以下能力：

• 数据感知（Data-aware）： 将语言模型连接到其他数据源
• 代理（Agentic）： 允许语言模型与其环境交互

LangChain 的主要价值主张是：

1. 组件（Components）： 用于使用语言模型的抽象，以及每个抽象的实现集合。无论您是否使用 LangChain 框架的其余部分，组件都是模块化且易于使用的
2. 开箱即用的链（Off-the-shelf chains）： 为实现特定高级任务而构建的结构化组件组装

开箱即用的链让您轻松上手。对于更复杂的应用程序和细微的用例，组件可以轻松定制现有链或构建新链。

这是什么？

大型语言模型（LLM）正成为一种变革性技术，使开发人员能够构建以前无法构建的应用程序。但孤立地使用这些 LLM 通常不足以创建真正强大的应用程序——真正的力量来自于将它们与其他计算或知识来源相结合。

本库旨在协助开发此类应用程序。

文档

在线文档可以在此找到。

演示

查看您可以下载和审查的演示项目。

与 JavaScript 和 Python LangChain 的关系

本库使用 Elixir 编写，旨在与 Elixir 应用程序一起使用。原始库是 LangChain JS/TS 和 LangChain Python。

JavaScript 和 Python 项目旨在尽可能无缝地相互集成。预期的集成非常强大，以至于所有对象（提示词、LLM、链等）的设计方式都使它们可以在两种语言之间序列化（serialized）和共享。

这个 Elixir 版本并不旨在与 JavaScript 和 Python 库完全对等。为什么不？

• JavaScript 和 Python 都是面向对象（Object Oriented）语言。Elixir 是函数式（Functional）语言。我们不会强制应用不适用的设计。
• JS 和 Python 版本在对话式 LLM 成为标准之前就开始开发了。当 LLM 不支持时，他们投入了大量精力来保留历史（如对话）。我们这里不这样做。

本库深受 JavaScript 库实际工作方式和与 LLM 交互方式的启发，并基于此构建。

安装

要求： Elixir 1.17 或更高版本

可以通过将 langchain 添加到 mix.exs 中的依赖列表来安装该包：

def deps do
  [
    {:langchain, "~> 0.6.0"}
  ]
end

配置

目前，该库编写为使用 Req 库进行 API（应用程序接口）调用。

您可以为 OpenAI 的 API 配置 组织 ID 和 API 密钥，但该库也适用于 其他兼容 API 以及其他服务，甚至 在 Bumblebee 上运行的本地模型。

config/runtime.exs：

config :langchain, openai_key: System.fetch_env!("OPENAI_API_KEY")
config :langchain, openai_org_id: System.fetch_env!("OPENAI_ORG_ID")
# 或
config :langchain, openai_key: "YOUR SECRET KEY"
config :langchain, openai_org_id: "YOUR_OPENAI_ORG_ID"

config :langchain, :anthropic_key, System.fetch_env!("ANTHROPIC_API_KEY")
config :langchain, :xai_api_key, System.fetch_env!("XAI_API_KEY")

可以使用函数或元组来解析密钥：

config :langchain, openai_key: {MyApp.Secrets, :openai_api_key, []}
config :langchain, openai_org_id: {MyApp.Secrets, :openai_org_id, []}
# 或
config :langchain, openai_key: fn -> System.fetch_env!("OPENAI_API_KEY") end
config :langchain, openai_org_id: fn -> System.fetch_env!("OPENAI_ORG_ID") end

API 密钥应被视为机密，不应检查到您的存储库中。

对于 fly.io，添加机密如下所示：

fly secrets set OPENAI_API_KEY=MyOpenAIApiKey
fly secrets set ANTHROPIC_API_KEY=MyAnthropicApiKey
fly secrets set XAI_API_KEY=MyXaiApiKey

要使用的模型列表：

• Anthropic Claude 模型
• AWS Bedrock 上的 Anthropic 模型
• OpenAI 模型
• Azure 上的 OpenAI 模型
• xAI Grok 模型
• Gemini AI 模型

提示词缓存 (Prompt caching)

ChatGPT、Claude 和 DeepSeek 都提供基于前缀的提示词缓存 (prefix-based prompt caching)，这对于较长的提示词可以提供成本和性能优势。Gemini 提供上下文缓存 (context caching)，类似。

• ChatGPT 的提示词缓存 对于超过 1024 tokens (令牌) 的提示词是自动的，缓存最长的公共前缀。
• Claude 的提示词缓存 不是自动的。它按顺序前缀化处理工具 (tools)、系统 (system) 和消息 (messages)，直至并包括标记为 {"cache_control": {"type": "ephemeral"}} 的块。参见 LangChain.ChatModels.ChatAnthropicTest 以获取示例。
• DeepSeek 的提示词缓存 为重复的提示词和系统消息提供自动缓存，有助于降低更长对话的成本并改善响应时间。
• Gemini 的上下文缓存 (context caching) 需要单独的调用，Langchain 不支持。

用法

本库的核心模块 (module) 是 LangChain.Chains.LLMChain。大多数其他部分要么是它的输入，要么是它使用的结构。要了解如何使用本库，请从这里开始。

xAI Grok 支持

LangChain 支持所有 xAI Grok 模型，包括高级的 Grok-4 变体：

alias LangChain.ChatModels.ChatGrok
alias LangChain.Chains.LLMChain
alias LangChain.Message

# Basic Grok-4 usage
{:ok, grok} = ChatGrok.new(%{model: "grok-4", temperature: 0.7})

{:ok, chain} =
  LLMChain.new!(%{llm: grok})
  |> LLMChain.add_message(Message.new_user!("Explain quantum computing"))
  |> LLMChain.run()

# Fast and efficient Grok-3-mini
{:ok, mini_grok} = ChatGrok.new(%{model: "grok-3-mini", temperature: 0.8})

Grok 模型提供独特的功能：

• 130K+ 上下文窗口 (context window) 用于广泛的对话
• 多代理推理 (Multi-agent reasoning) (Grok-4 Heavy) 多个代理协作
• 高级推理模式 (Advanced reasoning mode) 具有第一性原理思维
• 专用编码支持 (Specialized coding support) (Grok-4 Code)
• 多模态能力 (Multimodal capabilities) 包括视觉和图像分析

向 ChatGPT 暴露自定义 Elixir 函数

LangChain 的一个非常强大的功能是能够轻松地将大型语言模型 (LLM) 集成到您的应用程序中，并将功能、数据和功能从您的应用程序暴露给 LLM。

LangChain.Function 弥合了 LLM 和我们应用程序代码之间的差距。我们选择暴露什么，并使用 context（上下文），我们可以确保任何操作都限制在用户有权执行和访问的范围内。

有关交互式示例，请参阅项目 Livebook 笔记本 (notebook) "LangChain: Executing Custom Elixir Functions"。

下面是一个接收参数的函数示例。

alias LangChain.Function
alias LangChain.Message
alias LangChain.Chains.LLMChain
alias LangChain.ChatModels.ChatOpenAI
alias LangChain.Utils.ChainResult

# map of data we want to be passed as `context` to the function when
# executed.
custom_context = %{
  "user_id" => 123,
  "hairbrush" => "drawer",
  "dog" => "backyard",
  "sandwich" => "kitchen"
}

# a custom Elixir function made available to the LLM
custom_fn =
  Function.new!(%{
    name: "custom",
    description: "Returns the location of the requested element or item.",
    parameters_schema: %{
      type: "object",
      properties: %{
        thing: %{
          type: "string",
          description: "The thing whose location is being requested."
        }
      },
      required: ["thing"]
    },
    function: fn %{"thing" => thing} = _arguments, context ->
      # our context is a pretend item/location location map
      {:ok, context[thing]}
    end
  })

# create and run the chain
{:ok, updated_chain} =
  LLMChain.new!(%{
    llm: ChatOpenAI.new!(),
    custom_context: custom_context,
    verbose: true
  })
  |> LLMChain.add_tools(custom_fn)
  |> LLMChain.add_message(Message.new_user!("Where is the hairbrush located?"))
  |> LLMChain.run(mode: :while_needs_response)

# print the LLM's answer
IO.puts(ChainResult.to_string!(updated_chain))
# => "The hairbrush is located in the drawer."

替代 OpenAI 兼容 API (应用程序接口)

有几个服务或自托管应用程序提供用于类似 ChatGPT 行为的 OpenAI 兼容 API (OpenAI compatible API)。要使用此类服务，ChatOpenAI 结构体 (struct) 的 endpoint（端点）可以指向用于聊天的 API 兼容 endpoint。

例如，如果本地运行的服务提供该功能，以下代码可以连接到该服务：

{:ok, updated_chain} =
  LLMChain.new!(%{
    llm: ChatOpenAI.new!(%{endpoint: "http://localhost:1234/v1/chat/completions"}),
  })
  |> LLMChain.add_message(Message.new_user!("Hello!"))
  |> LLMChain.run()

Bumblebee 聊天支持

支持 Bumblebee 托管的聊天模型。内置支持 Llama 2、Mistral 和 Zephyr 模型。

目前，函数调用 (function calling) 仅支持 llama 3.1 Json Tool，不支持 Llama 2、Mistral 和 Zephyr。 notebook 文件夹中有一个示例 notebook。

ChatBumblebee.new!(%{
  serving: @serving_name,
  template_format: @template_format,
  receive_timeout: @receive_timeout,
  stream: true
})

serving 是托管模型的 Nx.Serving 的模块名称。

详见 LangChain.ChatModels.ChatBumblebee 文档。

测试

在运行实时 API 测试之前，您需要提供 API 密钥 (API keys)。复制示例文件并用您的值填充它：

cp .env.example .env

使用您的私有 API 密钥编辑 .env

.env 文件已被 Git 忽略 (gitignored)，并通过 dotenvy 由测试套件自动加载——无需 shell 设置或外部工具。

要运行所有测试，包括针对 OpenAI API 执行实时调用 (live calls) 的测试，请使用以下命令：

mix test --include live_call
mix test --include live_open_ai
mix test --include live_ollama_ai
mix test --include live_anthropic
mix test --include live_mistral_ai
mix test --include live_grok
mix test --include live_vertex_ai
mix test test/tools/calculator_test.exs --include live_call

注意： 这将使用配置好的 API 凭证，从而产生计费事件。

否则，运行以下命令将仅运行本地测试，不进行任何外部 API 调用：

mix test

执行特定测试，无论是否为 live_call，都会执行该测试并可能产生计费事件。

多模态 (Multi-modal) 支持：

LangChain 现在支持多模态 (multi-modal) 消息和工具结果。这意味着您可以使用 ContentParts 在单条消息中包含文本、图像、文件，甚至“思考”块。详见模块文档。此支持取决于 LLM（大型语言模型）和服务。并非所有模型都可能支持所有模态。

评估 Agent (智能体) 行为

在构建 Agent 系统时，最终答案只是故事的一部分。两个 Agent 可以通过非常不同的推理路径产生相同的答案——一个可能进行单次高效的工具调用，而另一个可能进行五次冗余调用。LangChain 提供 LangChain.Trajectory 来评估过程，而不仅仅是结果。

轨迹 (trajectory) 捕获 LLMChain 运行期间产生的工具调用结构化序列，支持回归测试、成本控制、安全验证和 Agent 工作流调试。

捕获轨迹 (Trajectory)

运行 chain 后，提取其轨迹：

alias LangChain.Trajectory

{:ok, chain} =
  LLMChain.new!(%{llm: llm})
  |> LLMChain.add_tools(my_tools)
  |> LLMChain.add_message(Message.new_user!("What's the weather in Paris?"))
  |> LLMChain.run(mode: :while_needs_response)

trajectory = Trajectory.from_chain(chain)
trajectory.tool_calls
#=> [%{name: "search", arguments: %{"query" => "weather paris"}},
#    %{name: "get_forecast", arguments: %{"city" => "Paris"}}]

匹配工具调用序列

使用 Trajectory.matches?/3 将实际工具调用与预期模式进行比较：

# Strict: exact order and arguments
Trajectory.matches?(trajectory, [
  %{name: "search", arguments: %{"query" => "weather paris"}},
  %{name: "get_forecast", arguments: %{"city" => "Paris"}}
])

# Wildcard arguments: pass nil to match any arguments
Trajectory.matches?(trajectory, [
  %{name: "search", arguments: nil},
  %{name: "get_forecast", arguments: nil}
])

# Unordered: same calls in any order
Trajectory.matches?(trajectory, expected, mode: :unordered)

# Superset: actual contains at least all expected calls
Trajectory.matches?(trajectory, [%{name: "search", arguments: nil}], mode: :superset)

# Subset args: expected arguments are a subset of actual
Trajectory.matches?(trajectory, expected, args: :subset)

ExUnit 断言

LangChain.Trajectory.Assertions 提供 assert_trajectory 和 refute_trajectory 宏，带有信息丰富的失败差异对比：

use LangChain.Trajectory.Assertions

test "agent calls the right tools in order" do
  trajectory = Trajectory.from_chain(chain)

  assert_trajectory trajectory, [
    %{name: "search", arguments: %{"query" => "weather"}},
    %{name: "get_forecast", arguments: nil}
  ]
end

test "agent does not call dangerous tools" do
  trajectory = Trajectory.from_chain(chain)

  refute_trajectory trajectory, [
    %{name: "delete_all", arguments: nil}
  ], mode: :superset
end

这两个宏也直接接受 LLMChain，自动提取轨迹。

黄金文件 (Golden-File) 测试

保存一个已知良好的轨迹，并将未来的运行结果与之比较以捕捉回归问题：

# Save the golden file
golden = chain |> Trajectory.from_chain() |> Trajectory.to_map()
File.write!("test/fixtures/weather_agent.json", Jason.encode!(golden))

# In your test
golden_map = "test/fixtures/weather_agent.json" |> File.read!() |> Jason.decode!()
expected = Trajectory.from_map(golden_map)
actual = Trajectory.from_chain(chain)

assert_trajectory actual, expected

检查轨迹 (Trajectories)

过滤和分组工具调用以进行更深入的分析：

# All calls to a specific tool
Trajectory.calls_by_name(trajectory, "search")

# Group calls by conversation turn
Trajectory.calls_by_turn(trajectory)
#=> [{0, [%{name: "search", ...}]}, {1, [%{name: "get_forecast", ...}]}]

# Check aggregated token usage
trajectory.token_usage
#=> %TokenUsage{input: 150, output: 45}

# Check metadata
trajectory.metadata
#=> %{model: "gpt-4", llm_module: LangChain.ChatModels.ChatOpenAI}

请参阅 LangChain.Trajectory 和 LangChain.Trajectory.Assertions 模块文档以获取完整的 API 参考。

Elixir LangChain 快速上手指南

Elixir LangChain 是一个专为 Elixir 应用程序设计的框架，用于集成 AI 服务（如 OpenAI、Anthropic 等）和自托管模型。它支持将语言模型与数据源连接，并允许模型与环境交互。

注意：此库是 Elixir 版本，不同于常见的 Python 或 JavaScript 版 LangChain。

环境准备

• Elixir 版本：1.17 或更高版本
• 依赖项：库内部使用 Req 进行 API 调用，安装时会自动处理。

安装步骤

1. 打开项目的 mix.exs 文件。
2. 在 deps 函数中添加 langchain 依赖：

def deps do
  [
    {:langchain, "~> 0.6.0"}
  ]
end

3. 获取依赖：

mix deps.get

配置 API 密钥

在 config/runtime.exs 中配置所需的 AI 服务密钥。建议使用环境变量管理敏感信息。

config :langchain, openai_key: System.fetch_env!("OPENAI_API_KEY")
config :langchain, openai_org_id: System.fetch_env!("OPENAI_ORG_ID")

# 如果使用 Anthropic
config :langchain, :anthropic_key, System.fetch_env!("ANTHROPIC_API_KEY")

也可以直接使用函数或元组来解析密钥：

config :langchain, openai_key: fn -> System.fetch_env!("OPENAI_API_KEY") end

基本使用

核心模块为 LangChain.Chains.LLMChain。以下是一个使用 OpenAI 模型进行对话的最小示例：

alias LangChain.ChatModels.ChatOpenAI
alias LangChain.Chains.LLMChain
alias LangChain.Message
alias LangChain.Utils.ChainResult

# 创建链并配置 LLM
{:ok, updated_chain} =
  LLMChain.new!(%{
    llm: ChatOpenAI.new!(),
    verbose: true
  })
  |> LLMChain.add_message(Message.new_user!("Hello!"))
  |> LLMChain.run()

# 输出结果
IO.puts(ChainResult.to_string!(updated_chain))

使用自定义工具（Function Calling）

你可以将 Elixir 函数暴露给 LLM，使其能够调用本地逻辑：

alias LangChain.Function

custom_fn =
  Function.new!(%{
    name: "get_item_location",
    description: "Returns the location of the requested item.",
    parameters_schema: %{
      type: "object",
      properties: %{
        item: %{type: "string", description: "The item to locate."}
      },
      required: ["item"]
    },
    function: fn %{"item" => item}, _context ->
      {:ok, "The #{item} is in the drawer."}
    end
  })

# 将工具添加到链中
{:ok, chain} =
  LLMChain.new!(%{llm: ChatOpenAI.new!()})
  |> LLMChain.add_tools(custom_fn)
  |> LLMChain.add_message(Message.new_user!("Where is the hairbrush?"))
  |> LLMChain.run(mode: :while_needs_response)

更多详细用法请参考 官方文档。