instructor_ex

使用 OpenAI（及开源大语言模型 LLM，Large Language Model）实现结构化 Ecto（Elixir 的 ORM 框架）输出

---

查看我们的快速入门指南，几分钟内即可开始使用 Instructor。

Instructor 为大语言模型（LLM）提供结构化提示。它是对 @jxnlco 开发的优秀 Instructor Python 库 的精神移植。

Instructor 允许你使用 Ecto 从 LLM 获取结构化输出。
你无需定义任何 JSON 模式（schema）。
你可以像以往一样使用 Ecto。
并且由于它只是 Ecto，你可以提供变更集（changeset）验证，以确保从 LLM 获取的内容不仅结构正确，而且语义正确。

要了解更多关于 Instructor 的设计理念及其动机，请查看这次 Elixir Denver Meetup 演讲：

虽然 Instructor 是为与 OpenAI 配合使用而设计的，但它也支持所有主要 AI 实验室和开源 LLM 推理服务器：

• OpenAI
• Anthropic
• Groq
• Ollama
• Gemini
• vLLM
• llama.cpp

最简单的使用方式非常直接：

1. 创建一个 ecto 模式（schema），其中包含一个 @llm_doc 字符串，用于向 LLM 解释模式定义。
2. 在模式上定义 validate_changeset/1 函数，并使用 use Instructor 宏，以便 Instructor 能够识别它。
3. 调用 Instructor.chat_completion/1，向 LLM 提供执行指令。

你可以使用 max_retries 参数自动、迭代地与 LLM 交互，以尝试修复出现的验证错误。

Mix.install([:instructor])

defmodule SpamPrediction do
  use Ecto.Schema
  use Validator

  @llm_doc """
  ## Field Descriptions:
  - class: Whether or not the email is spam.
  - reason: A short, less than 10 word rationalization for the classification.
  - score: A confidence score between 0.0 and 1.0 for the classification.
  """
  @primary_key false
  embedded_schema do
    field(:class, Ecto.Enum, values: [:spam, :not_spam])
    field(:reason, :string)
    field(:score, :float)
  end

  @impl true
  def validate_changeset(changeset) do
    changeset
    |> Ecto.Changeset.validate_number(:score,
      greater_than_or_equal_to: 0.0,
      less_than_or_equal_to: 1.0
    )
  end
end

is_spam? = fn text ->
  Instructor.chat_completion(
    model: "gpt-4o-mini",
    response_model: SpamPrediction,
    max_retries: 3,
    messages: [
      %{
        role: "user",
        content: """
        Your purpose is to classify customer support emails as either spam or not.
        This is for a clothing retail business.
        They sell all types of clothing.

        Classify the following email: 

        <email>
          #{text}
        </email>
        """
      }
    ]
  )
end

is_spam?.("Hello I am a Nigerian prince and I would like to send you money")

# => {:ok, %SpamPrediction{class: :spam, reason: "Nigerian prince email scam", score: 0.98}}

安装

在你的 mix.exs 文件中，

def deps do
  [
    {:instructor, "~> 0.1.0"}
  ]
end

instructor 快速上手指南

环境准备

• 系统要求：支持 Elixir 的操作系统（Linux/macOS 推荐，Windows 需使用 WSL2）
• 前置依赖：
  • Elixir 1.14+ 和 Erlang 25+（通过 asdf 或官方安装包配置）
  • 有效的 LLM 服务 API 密钥（如 OpenAI API Key，需提前在 OpenAI 平台申请）
  • 国内加速推荐：设置 Hex 中国镜像源（阿里云提供），执行以下命令加速依赖下载：

    mix hex.config mirror_url "https://hex.cn"
    

安装步骤

在 Elixir 项目中编辑 mix.exs 文件，添加依赖项：

def deps do
  [
    {:instructor, "~> 0.1.0"}
  ]
end

执行依赖安装：

mix deps.get

基本使用

以下是最简示例：定义结构化输出 schema 并调用 LLM 生成验证后的数据。

1. 创建 Ecto schema 模块（spam_prediction.ex），使用 @llm_doc 描述字段要求
2. 实现 validate_changeset/1 确保输出符合业务逻辑
3. 通过 Instructor.chat_completion 发送请求

defmodule SpamPrediction do
  use Ecto.Schema
  use Validator

  @llm_doc """
  ## Field Descriptions:
  - class: Whether or not the email is spam.
  - reason: A short, less than 10 word rationalization for the classification.
  - score: A confidence score between 0.0 and 1.0 for the classification.
  """
  @primary_key false
  embedded_schema do
    field(:class, Ecto.Enum, values: [:spam, :not_spam])
    field(:reason, :string)
    field(:score, :float)
  end

  @impl true
  def validate_changeset(changeset) do
    changeset
    |> Ecto.Changeset.validate_number(:score,
      greater_than_or_equal_to: 0.0,
      less_than_or_equal_to: 1.0
    )
  end
end

is_spam? = fn text ->
  Instructor.chat_completion(
    model: "gpt-4o-mini",
    response_model: SpamPrediction,
    max_retries: 3,
    messages: [
      %{
        role: "user",
        content: """
        Your purpose is to classify customer support emails as either spam or not.
        This is for a clothing retail business.
        They sell all types of clothing.

        Classify the following email: 

        <email>
          #{text}
        </email>
        """
      }
    ]
  )
end

is_spam?.("Hello I am a Nigerian prince and I would like to send you money")

执行后将返回结构化结果（示例）：

{:ok, %SpamPrediction{class: :spam, reason: "Nigerian prince email scam", score: 0.98}}

关键提示

• 必须设置 OPENAI_API_KEY 环境变量（其他 LLM 服务需配置对应凭证）
• model 参数支持国内可访问的服务（如 qwen-max 需通过阿里云百炼平台配置）
• 通过 max_retries 自动修复验证错误，无需手动处理 JSON 解析