Ash AI 使用指南：Elixir 框架中的 AI 集成方案

概述

Ash AI 是 Ash 框架的一个扩展模块，它将现代人工智能能力无缝集成到 Elixir 应用开发中。作为 Ash 生态系统的智能增强组件，它提供了向量化处理、大语言模型交互和 AI 工具集成等核心功能，使开发者能够轻松构建智能化的数据驱动应用。

核心概念解析

向量化技术

向量化是将文本数据转换为数值向量（嵌入）的过程，这是实现语义搜索的基础。Ash AI 的向量化功能包含以下关键要素：

1. 文本预处理：通过组合多个属性构建完整的上下文文本
2. 嵌入模型：将文本转换为高维向量表示
3. 更新策略：控制向量生成的时机和方式

AI 工具系统

Ash AI 允许将资源操作暴露为 AI 可调用的工具，实现以下功能：

• 自然语言接口访问数据库操作
• 构建自动化工作流
• 创建智能代理系统

提示驱动动作

这是一种创新的动作实现方式，其业务逻辑由大语言模型动态生成，特点包括：

• 基于自然语言描述定义动作行为
• 支持结构化输出约束
• 可集成外部工具调用

向量化实战指南

基础配置

在资源中启用向量化需要三个步骤：

defmodule MyApp.Article do
  use Ash.Resource, extensions: [AshAi]

  vectorize do
    full_text do
      text(fn record ->
        """
        标题: #{record.title}
        内容: #{record.content}
        作者: #{record.author.name}
        """
      end)
      used_attributes [:title, :content, :author_id]
    end

    strategy :ash_oban
    embedding_model MyApp.EmbeddingModel
  end
end

嵌入模型实现

嵌入模型是将文本转换为向量的核心组件，以下是 OpenAI 模型的实现示例：

defmodule MyApp.OpenAiEmbeddingModel do
  use AshAi.EmbeddingModel

  @impl true
  def dimensions(_opts), do: 3072

  @impl true
  def generate(texts, _opts) do
    # 实际实现中应考虑错误处理和重试机制
    response = Req.post!("https://api.openai.com/v1/embeddings", ...)
    
    response.body["data"]
    |> Enum.map(& &1["embedding"])
    |> then(&{:ok, &1})
  end
end

更新策略选择

根据应用场景选择合适的向量更新策略：

策略类型	特点	适用场景
:after_action	同步更新，简单直接	开发环境、小规模数据
:ash_oban	异步任务队列更新	生产环境、大规模数据
:manual	完全手动控制	特殊需求场景

语义搜索实现

利用向量实现高级搜索功能：

read :semantic_search do
  argument :query, :string, allow_nil?: false

  prepare fn query, _context ->
    {:ok, [embedding]} = MyApp.EmbeddingModel.generate([query.arguments.query])
    
    query
    |> Ash.Query.filter(vector_cosine_distance(content_vector, ^embedding) < 0.3)
    |> Ash.Query.sort(asc: vector_cosine_distance(content_vector, ^embedding))
  end
end

AI 工具系统详解

工具注册与配置

在领域模块中声明可用的 AI 工具：

defmodule MyApp.Blog do
  use Ash.Domain, extensions: [AshAi]

  tools do
    tool :search_articles, MyApp.Article, :search do
      description "根据关键词搜索相关文章"
    end
    
    tool :create_comment, MyApp.Comment, :create
  end
end

数据访问控制

通过 public? 标记控制工具的数据访问权限：

attributes do
  attribute :title, :string, public?: true
  attribute :content, :string, public?: true
  attribute :draft, :boolean  # 默认 private
end

relationships do
  belongs_to :author, MyApp.User, public?: true
end

访问规则矩阵：

操作类型	可访问性
过滤/排序	仅 public 属性
参数传递	仅 public 参数
响应数据	默认仅 public，可通过 load 加载私有数据

提示驱动动作开发

基础实现

创建由 LLM 实现的资源动作：

action :summarize, :string do
  argument :length, :string, constraints: [one_of: ["short", "medium", "long"]]
  
  run prompt(
    ChatOpenAI.new!(%{model: "gpt-4"}),
    prompt: """
    请将以下文章内容总结为<%= @input.arguments.length %>版本：
    <%= @input.arguments.text %>
    """
  )
end

高级模式

支持复杂交互场景的实现方式：

action :analyze_trend, {:array, :string} do
  run prompt(
    fn _input, _context ->
      ChatOpenAI.new!(%{
        model: "gpt-4",
        api_key: System.get_env("OPENAI_KEY")
      })
    end,
    tools: [:search_articles, :get_statistics],
    prompt: {
      "你是一个数据分析专家",
      "分析当前行业趋势并给出建议"
    }
  )
end

生产环境部署建议

MCP 服务配置

实现安全的 AI 工具访问接口：

# 认证管道
pipeline :mcp_auth do
  plug AshAuthentication.Strategy.ApiKey.Plug,
    resource: MyApp.Accounts.User,
    required?: true
end

# 路由配置
scope "/mcp" do
  pipe_through [:api, :mcp_auth]
  
  forward "/", AshAi.Mcp.Router,
    tools: [:search_articles, :create_comment],
    protocol_version: "2024-11-05"
end

性能优化

1. 向量索引：考虑使用专门的向量数据库扩展
2. 缓存策略：对常见查询结果实现缓存
3. 批量处理：对大量文本使用批量嵌入生成

测试策略

确保 AI 组件可靠性的测试方法：

1. 嵌入模型测试：

test "embedding generation" do
  assert {:ok, [embedding]} = EmbeddingModel.generate(["测试文本"])
  assert length(embedding) == 3072
end

2. 语义搜索测试：

test "semantic search" do
  article = create_article(title: "Elixir 编程", content: "函数式编程语言")
  results = Article.search!("函数语言")
  assert article.id in Enum.map(results, & &1.id)
end

3. 提示动作测试：

test "summary generation" do
  {:ok, summary} = Article.summarize(text: "长文本...", length: "short")
  assert String.length(summary) < 100
end

最佳实践

1. 渐进式采用：从简单功能开始，逐步增加复杂度
2. 监控：记录 AI 操作的性能和准确性指标
3. 用户反馈：建立机制收集终端用户对 AI 功能的反馈
4. 安全边界：为所有 AI 操作设置合理的超时和重试限制

通过 Ash AI，开发者可以构建出真正智能化的 Elixir 应用，将结构化数据与自然语言处理能力完美结合，为用户提供更直观、更强大的交互体验。