AI驱动IaC生成器aiac：用自然语言生成Terraform、K8s等基础设施代码

1. 项目概述：当AI大模型遇见基础设施即代码

如果你是一名运维工程师、DevOps开发者或者云架构师，那么“基础设施即代码”这个概念对你来说一定不陌生。从Terraform、Pulumi到Ansible，我们花了大量时间学习这些工具的语法、最佳实践，并编写和维护那些动辄成百上千行的配置文件。这过程虽然规范，但有时也略显枯燥和重复。有没有一种可能，让我们能用更自然、更高效的方式来生成这些代码？比如，直接告诉AI：“给我来一份高可用的AWS EKS集群的Terraform配置”，然后它就能生成一份可直接使用或稍作修改的代码？这正是gofireflyio/aiac这个项目试图解决的问题。

aiac是一个命令行工具兼Go语言库，它的核心定位是“AI驱动的IaC生成器”。它本身不提供AI能力，而是作为一个智能的“翻译官”和“接线员”，将你用自然语言描述的基础设施需求，精准地“翻译”成对后端大型语言模型的提示词，再将模型返回的结果解析、提取成你想要的代码文件。它支持OpenAI API、Amazon Bedrock以及本地部署的Ollama等多种LLM提供商，让你可以灵活地选择最适合自己的AI引擎。简单来说，它让生成Terraform模块、Kubernetes清单、Dockerfile乃至CI/CD流水线脚本，变得像聊天一样简单。

2. 核心设计思路与架构解析

2.1 为什么需要aiac？不仅仅是另一个AI聊天工具

市面上已经有很多AI代码助手，比如GitHub Copilot、Cursor，它们也能根据注释生成代码片段。那么，aiac的独特价值在哪里？我认为关键在于它的“领域专注性”和“工作流集成度”。

首先，领域专注性。通用AI助手在面对“创建一个S3桶”这样的需求时，可能会生成一段Python的boto3代码，或者一段AWS CLI命令，这取决于它对你上下文的理解。而aiac通过其精心设计的提示词工程，会明确引导模型生成特定于“基础设施即代码”领域的输出，例如Terraform的HCL、CloudFormation的YAML或Pulumi的代码。它减少了歧义，提高了输出结果的准确性和可用性。

其次，工作流集成度。aiac不仅仅是一个生成代码的“黑盒”。它提供了完整的命令行交互体验：生成代码后，你可以直接进入一个交互式会话，要求模型对代码进行解释、修改、优化，或者基于之前的对话历史继续生成新的相关代码。更重要的是，它提供了诸如--output-file、--clipboard等实用参数，能够无缝地将生成的代码保存到文件或复制到剪贴板，直接嵌入到你现有的编辑和版本控制工作流中。这种设计让它从一个“玩具”变成了一个真正的“生产力工具”。

2.2 核心架构：配置、后端与交互模型

aiac的架构清晰且灵活，主要围绕三个核心概念构建：配置、后端和交互模型。

1. 配置中心化从v5版本开始，aiac摒弃了通过繁琐的命令行参数传递API密钥、端点等配置的方式，转而采用一个TOML格式的配置文件。这个文件通常位于~/.config/aiac/aiac.toml。这种设计的好处显而易见：

• 安全性：敏感信息如API密钥不再暴露在命令行历史或环境变量中（尽管也支持引用环境变量）。
• 灵活性：你可以轻松定义多个“后端”，每个后端对应一个LLM提供商或同一提供商的不同环境（如开发、生产）。例如，你可以同时配置一个使用GPT-4的OpenAI后端和一个使用Claude的Amazon Bedrock后端，根据任务需求随时切换。
• 可维护性：所有配置集中一处，管理和版本控制（如使用dotfiles）变得非常方便。

2. 后端抽象层“后端”是aiac架构中的关键抽象。它封装了与特定LLM提供商API通信的所有细节。目前支持三种类型：

• openai：兼容OpenAI API格式的后端，不仅可用于官方的OpenAI服务，也可用于Azure OpenAI或任何部署了兼容API的服务（如LocalAI）。
• bedrock：用于AWS Bedrock服务，利用AWS SDK进行身份认证和请求签名，无缝集成AWS生态。
• ollama：用于本地运行的Ollama服务，适合在离线或内网环境中使用私有模型。

每个后端在配置文件中都有一个唯一的名称（如my_openai），并包含type、api_key（或AWS认证信息）、url（可选）等必要属性。这种设计使得添加新的LLM提供商支持变得模块化。

3. 交互式聊天模型aiac内部使用“聊天模型”与LLM交互，而非旧的“补全模型”。这是一个重要的设计决策。聊天模型（如GPT-4、Claude）支持多轮对话，能更好地理解上下文和复杂指令。aiac会构建一个包含系统提示词和用户消息的对话，发送给后端。系统提示词会明确要求模型以特定格式（如代码块）输出所需内容，这极大地提高了输出代码的结构化程度和准确性。

3. 从零开始：安装、配置与初体验

3.1 安装方式选择与实操

aiac提供了多种安装方式，你可以根据自身环境选择最顺手的一种。

1. 使用Homebrew（macOS/Linux）这是最推荐的方式之一，便于后续升级。

brew tap gofireflyio/aiac https://github.com/gofireflyio/aiac brew install aiac

安装完成后，直接在终端输入aiac --version验证是否成功。

2. 使用Docker如果你不想在本地安装Go环境或依赖，Docker是最干净的选择。

docker pull ghcr.io/gofireflyio/aiac

运行命令时，需要将本地的配置文件目录挂载到容器内：

docker run -it -v ~/.config/aiac:/root/.config/aiac ghcr.io/gofireflyio/aiac --help

3. 使用Go Install如果你本身就是Go开发者，这种方式最直接。

go install github.com/gofireflyio/aiac/v5@latest

安装后，可执行文件通常位于$GOPATH/bin或$GOBIN目录下，请确保该目录已在你的系统PATH中。

4. 从源码构建适合想要贡献代码或体验最新开发版的用户。

git clone https://github.com/gofireflyio/aiac.git cd aiac go build -o aiac .

编译生成的aiac二进制文件可以直接运行。

注意：无论哪种安装方式，请确保你的网络环境能够正常访问你所选择的LLM提供商API（如api.openai.com或AWS服务端点）。对于Ollama，则需要确保本地ollama serve服务正在运行。

3.2 配置文件详解与多环境配置实战

配置文件是aiac的核心。我们来创建一个功能齐全的配置示例，涵盖常见场景。

首先，创建配置目录和文件：

mkdir -p ~/.config/aiac vim ~/.config/aiac/aiac.toml

下面是一个综合性的配置文件内容及解析：

# 默认后端。如果不指定-b参数，aiac将使用这个后端。 default_backend = "openai_prod" # 1. 官方OpenAI后端 (使用GPT-4o) [backends.openai_prod] type = "openai" # 建议将API_KEY存储在环境变量中，通过$引用，避免密钥硬编码。 api_key = "$OPENAI_API_KEY" # 为该后端设置默认模型，这样在命令中就不必每次都指定-m参数。 default_model = "gpt-4o" # 2. Azure OpenAI后端 [backends.azure_openai_dev] type = "openai" # Azure OpenAI的端点URL格式特殊，包含部署名。 url = "https://your-resource.openai.azure.com/openai/deployments/your-deployment-name" api_key = "$AZURE_OPENAI_KEY" # Azure使用api-key作为认证头，而非默认的Authorization。 auth_header = "api-key" # 可选：指定API版本。 api_version = "2024-02-15" # 可选：添加额外的HTTP头，适用于一些网关或代理需求。 extra_headers = { X-Custom-Source = "aiac-tool" } # 3. AWS Bedrock后端 (生产环境) [backends.bedrock_prod] type = "bedrock" # 使用命名AWS配置文件，管理不同账号的密钥和区域。 aws_profile = "prod" aws_region = "us-east-1" # 指定Bedrock上的模型ID，例如Claude 3 Sonnet。 default_model = "anthropic.claude-3-sonnet-20240229-v1:0" # 4. AWS Bedrock后端 (开发环境，使用不同区域和模型) [backends.bedrock_dev] type = "bedrock" aws_profile = "dev" aws_region = "ap-southeast-1" default_model = "anthropic.claude-3-haiku-20240307-v1:0" # 5. 本地Ollama后端 [backends.local_llama] type = "ollama" # 默认就是http://localhost:11434/api，这里显式写出以示清晰。 url = "http://localhost:11434/api" # 指定本地运行的模型名称，如llama3:8b。 default_model = "llama3:8b" # 可以为Ollama添加认证头（如果前面有代理网关的话）。 # extra_headers = { Authorization = "Bearer your-proxy-token" }

关键配置解析与避坑指南：

• api_key引用环境变量：使用$VAR_NAME语法是安全最佳实践。确保在运行aiac前，这些环境变量已正确设置（例如在~/.bashrc或~/.zshrc中export）。
• Azure OpenAI的auth_header：这是最容易出错的地方。Azure OpenAI服务要求使用api-key头，而OpenAI官方使用Authorization头。配置错误会导致401认证失败。
• AWS Bedrock的准备工作：使用Bedrock后端前，必须确保：1) 目标AWS账号已开通Bedrock服务；2) 你打算使用的模型（如Claude）在该区域已“启用”；3) 对应的IAM身份（通过aws_profile指定）有调用BedrockInvokeModelAPI的权限。
• Ollama连接：确保Ollama服务已启动（ollama serve），并且你已通过ollama pull拉取了配置中指定的模型。aiac不会帮你拉取模型。

3.3 第一行AI生成的IaC代码

配置完成后，让我们进行第一次生成。假设我们使用默认的openai_prod后端。

1. 列出可用模型（可选）首先，可以查看你的后端支持哪些模型：

aiac -b openai_prod --list-models

这会调用对应API列出模型。对于OpenAI，你会看到gpt-4o、gpt-4-turbo等；对于Bedrock，会列出你账号下已启用的模型。

2. 生成一个简单的Terraform配置我们从一个简单的需求开始：

aiac terraform for an AWS S3 bucket with versioning enabled

按下回车后，aiac会：

1. 使用默认后端（或-b指定的后端）和默认模型。
2. 将你的自然语言提示，结合内部的系统指令，发送给LLM。
3. 接收Markdown格式的响应。
4. 自动提取响应中的代码块（例如被hcl或terraform包裹的部分）。
5. 将提取的代码输出到终端，并自动进入交互模式。

你可能会看到如下输出：

# 生成的Terraform代码示例 provider "aws" { region = "us-east-1" } resource "aws_s3_bucket" "example_bucket" { bucket = "my-unique-bucket-name" # 请更改为全局唯一的名称 tags = { Name = "My Example Bucket" Environment = "Dev" } } resource "aws_s3_bucket_versioning" "example_versioning" { bucket = aws_s3_bucket.example_bucket.id versioning_configuration { status = "Enabled" } }

输出后，终端会显示一个提示符（如(aiac)），表示你已进入交互式会话。你可以继续输入指令，例如：“Change the region to eu-central-1” 或 “Add a lifecycle rule to expire noncurrent versions after 30 days”。模型会基于之前的对话历史，生成更新后的代码。

3. 非交互式快速生成如果你只想快速获取代码并保存，可以使用-q（quiet）参数退出交互模式，并结合--output-file保存到文件。

aiac -q terraform for an AWS S3 bucket with versioning enabled --output-file=s3_bucket.tf

这样，代码会直接保存到s3_bucket.tf文件中，且命令行立即返回。

4. 高级用法与场景化实战

4.1 超越Terraform：全栈配置生成

aiac的能力远不止生成Terraform。它的设计目标是成为基础设施和配置的通用生成器。

场景一：生成Kubernetes部署清单你需要一个部署Nginx并配置健康检查的K8s Deployment和Service。

aiac kubernetes manifest for nginx deployment with liveness and readiness probes, and a LoadBalancer service

它会生成完整的YAML，包含Deployment、Service，并正确配置了livenessProbe和readinessProbe。

场景二：生成Dockerfile为你的Python Flask应用生成一个生产环境优化的Dockerfile。

aiac dockerfile for python flask app using alpine base image, multi-stage build, and running as non-root user

aiac会生成一个使用python:3.11-alpine作为基础镜像、包含pip install --no-cache-dir、创建非root用户并正确设置工作目录和权限的Dockerfile。

场景三：生成CI/CD流水线为你的Terraform项目生成一个GitHub Actions工作流，实现plan和apply的自动化，并仅在合并到主分支时执行apply。

aiac github action workflow for terraform that runs terraform fmt, init, validate, plan on pull request, and apply only on merge to main branch

生成的YAML会包含多个job，正确设置环境变量、缓存依赖，并使用hashFiles来触发。

场景四：生成策略即代码为Kubernetes生成一个Open Policy Agent策略，要求所有Pod必须设置资源请求和限制。

aiac rego policy for kubernetes that enforces resource requests and limits on all pods

这会生成一段Rego代码，你可以将其保存为require-resources.rego并集成到你的OPA Gatekeeper或Kyverno策略中。

4.2 命令行构建器与查询构建器：提升日常效率

这是aiac非常实用的两个功能，它能帮你回忆或构建复杂的命令行或查询语句。

命令行构建器： 当你忘记了一个复杂的kubectl或awscli命令的具体参数时，可以直接问aiac。

aiac kubectl command to get all pods across all namespaces with their node names and status

输出：kubectl get pods --all-namespaces -o=custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,NODE:.spec.nodeName,STATUS:.status.phase

查询构建器： 编写复杂的数据库查询时，可以用自然语言描述逻辑。

aiac sql query for postgresql that finds duplicate email addresses in a users table

输出：

SELECT email, COUNT(*) as count FROM users GROUP BY email HAVING COUNT(*) > 1;

4.3 集成到脚本与自动化流程中

aiac的-q（安静模式）和文件输出功能，使其非常适合集成到自动化脚本中。

示例：自动生成并应用基础设施变更假设你有一个脚本，需要根据环境变量动态生成不同的Terraform后端配置。

#!/bin/bash ENVIRONMENT=${1:-dev} REGION=${2:-us-west-2} # 使用aiac生成特定于环境的backend.tf aiac -q --backend=openai_prod \ "terraform backend configuration using s3 for state file, dynamodb for locking. bucket name should be mycompany-tfstate-\$ENVIRONMENT, key is \${ENVIRONMENT}/network/terraform.tfstate, region is \$REGION" \ --output-file=backend.tf # 检查生成的文件 cat backend.tf # 后续可以继续运行 terraform init, plan, apply...

在这个脚本中，aiac根据传入的环境和区域参数，动态生成了对应的S3后端配置，实现了配置的代码化生成。

5. 深入原理：aiac如何与LLM协作

理解aiac的工作原理，有助于你写出更精准的提示词，获得更高质量的代码。

5.1 提示词工程：从用户输入到模型指令

当你输入aiac terraform for an AWS VPC with public and private subnets时，aiac并不会简单地将这句话直接扔给LLM。它会在后台构建一个结构化的聊天请求。

一个简化版的内部提示词组装过程如下：

1. 系统提示词：这是一个固定的、引导模型角色的指令。类似于：

   “你是一个专业的基础设施即代码工程师。请根据用户请求，生成准确、符合最佳实践、可直接运行的代码。输出时，请将代码包裹在带有正确语言标识的代码块中（例如 ```hcl, ```yaml）。只输出代码和必要的简短解释，不要输出其他无关内容。”

2. 用户消息：aiac会对你的原始输入进行轻微的清理（例如移除v5之前版本遗留的“get”前缀），然后将其作为用户消息。
3. 对话历史：在交互模式下，之前的问答回合会作为上下文附加到新请求中，让模型能理解并延续对话。

这种设计确保了模型输出高度结构化（代码块），并且聚焦于生成可用的代码，而不是冗长的论述。

5.2 输出处理与交互会话管理

模型返回的是一个Markdown格式的响应。aiac的核心任务之一就是从中精准地提取代码。

• 代码块检测：aiac会扫描响应，寻找被 ``` 包裹的代码块。它会尝试使用代码块上标注的语言（如hcl,terraform,yaml,dockerfile）作为文件扩展名的参考。
• 多代码块处理：如果响应中包含多个代码块（例如一个Terraform文件和一个说明性的Shell脚本），aiac在交互模式下会依次展示它们。在使用--output-file时，默认会将第一个代码块保存到指定文件。如果同时使用--readme-file，可能会将整个Markdown响应或非代码部分保存。
• 会话状态：在交互模式下，aiac会在内存中维护一个会话对象，其中保存了与当前后端、模型的完整对话历史。每次你输入新指令，都会将整个历史发送给模型，从而实现连贯的、上下文感知的对话。你可以要求它“修改刚才生成的VPC，将CIDR块改为10.1.0.0/16”，模型能准确理解“刚才生成的VPC”指的是什么。

5.3 错误处理与API限制

aiac本身是一个轻量的中间层，大部分错误来源于底层的LLM提供商API。

• 配额不足/速率限制：这是最常见的问题。OpenAI有每分钟/每天的请求和Token限制。当看到类似“Rate limit reached”或“insufficient_quota”的错误时，你需要：1) 检查OpenAI账户的用量和配额；2) 如果是免费额度用完，需要绑定支付方式；3) 在自动化脚本中主动加入延迟（例如sleep）来规避速率限制。
• 模型不可用/未启用：在使用Bedrock时，如果看到“Model ... is not accessible”之类的错误，说明你指定的模型ID在当前区域对你的账户未启用。你需要登录AWS Bedrock控制台，在“Model access”部分申请启用该模型。
• 上下文长度超限：虽然aiac使用聊天模型避免了旧版补全模型的token限制问题，但对话历史过长仍可能超过模型自身的上下文窗口。如果发生这种情况，模型可能会截断回复或返回错误。在交互式对话非常长时，可以考虑开始一个新会话（退出aiac重新运行）。
• 网络问题：对于Ollama后端，确保localhost:11434可访问。对于云服务，检查网络代理或防火墙设置。

6. 常见问题排查与实战技巧

6.1 配置与连接问题

问题1：运行aiac提示“no backends configured”或“backend not found”。

• 排查：首先检查配置文件路径是否正确。使用aiac --config /full/path/to/aiac.toml ...显式指定路径测试。其次，检查配置文件语法，TOML文件对格式要求严格，确保[backends.xxx]部分书写正确，没有缺少括号或引号。
• 技巧：可以使用tomlv或在线TOML校验器检查配置文件格式。

问题2：使用OpenAI后端时，报错“Authentication error”。

• 排查：
  1. 确认api_key配置正确。如果是引用环境变量$OPENAI_API_KEY，请在终端执行echo $OPENAI_API_KEY确认其值已设置且未过期。
  2. 如果使用Azure OpenAI，务必确认auth_header = "api-key"已设置，并且url指向了正确的部署端点（应包含/deployments/{deployment-name}）。
  3. 对于OpenAI官方API，密钥通常以sk-开头。

问题3：使用Bedrock后端时，报错“AccessDeniedException”或“Model not found”。

• 排查：
  1. 确认AWS CLI已配置，且aws_profile指定的profile拥有调用bedrock:InvokeModel的权限。
  2. 在终端运行aws bedrock list-foundation-models --profile your-profile --region your-region，查看模型列表，确认你使用的default_model（如anthropic.claude-3-sonnet-20240229-v1:0）存在于列表中且状态为AVAILABLE。
  3. 你需要通过AWS控制台手动“启用”你想使用的模型。

问题4：使用Ollama后端时，连接被拒绝。

• 排查：
  1. 运行ollama serve确保服务已启动。
  2. 运行curl http://localhost:11434/api/tags测试API是否正常响应。
  3. 检查aiac.toml中Ollama后端的url配置，确保端口正确（默认11434）。
  4. 如果你通过Docker使用Ollama，注意容器网络。aiac容器需要能访问到宿主机的Ollama服务，可能需要使用host网络或指定特殊IP（如http://host.docker.internal:11434/api）。

6.2 生成内容优化技巧

技巧1：提示词越具体，输出质量越高。

• 不佳示例：aiac terraform for ec2
• 优秀示例：aiac terraform for an AWS EC2 instance of type t3.micro, with an Ubuntu 22.04 AMI, in a public subnet, with a security group allowing SSH from my IP only, and an associated elastic IP. Use latest AWS provider.后者指定了实例类型、镜像、网络位置、安全规则、附加资源和使用条件，生成的代码几乎开箱即用。

技巧2：利用交互模式进行迭代和修正。不要期望一次生成完美代码。首先生成一个基础版本，然后进入交互模式进行细化。

$ aiac terraform for a secure AWS S3 bucket ... (输出基础代码) (aiac) Make it private and enable server-side encryption with AWS KMS. (aiac) Add a lifecycle rule to transition objects to Glacier after 30 days. (aiac) Output the bucket ARN as an output variable.

通过多轮对话，你可以逐步完善配置，这比尝试在单次提示中描述所有细节更有效。

技巧3：处理模型“幻觉”或过时信息。LLM可能生成使用已弃用参数或语法的代码。例如，旧的Terraform AWS Provider版本中的某些参数可能在新版本中已变更。

• 对策：在提示词中指定版本。例如：aiac terraform using AWS provider version 5.0 or above for an S3 bucket。
• 必要步骤：生成任何代码后，尤其是用于生产环境前，务必使用对应工具的命令行进行验证（如terraform validate，docker build的--dry-run，kubectl apply --dry-run=client）。

技巧4：生成多文件项目结构。对于复杂的基础设施，你可能需要多个文件（如main.tf,variables.tf,outputs.tf）。你可以分步生成：

$ aiac -q terraform module structure for an AWS VPC with public and private subnets, NAT gateway, and internet gateway. Output the main configuration in main.tf --output-file=main.tf $ aiac -q now generate a variables.tf for the above VPC module with sensible defaults --output-file=variables.tf $ aiac -q now generate an outputs.tf exposing vpc_id, public and private subnet ids --output-file=outputs.tf

或者，在交互模式中一次性请求：“Generate a complete Terraform module with separate main.tf, variables.tf and outputs.tf for ...”，模型可能会在一个响应中用多个代码块分别给出，你需要手动拆分保存。

6.3 性能与成本考量

成本控制：

• 模型选择：GPT-4系列比GPT-3.5系列强大但也昂贵得多。对于生成结构良好的IaC代码，GPT-3.5-turbo通常已足够，且成本大幅降低。在aiac.toml中为不同后端设置性价比高的default_model。
• 提示词精炼：避免在提示词中包含大量无关的背景信息。清晰、简洁的指令能减少输入的Token数，从而降低成本。
• 使用本地模型：对于日常的、非关键性的代码生成，使用本地的Ollama搭配llama3、codellama等模型，可以实现零成本、低延迟的体验，尽管生成质量可能略低于顶级商用模型。

响应速度：

• 云服务（OpenAI， Bedrock）的响应速度取决于模型和网络。GPT-4o通常比GPT-4 Turbo快。
• 本地Ollama的响应速度极快，几乎没有延迟，体验流畅。
• 如果感觉云服务响应慢，可以尝试在aiac命令前使用time命令测量，并考虑是否是网络问题。

7. 从v4升级到v5的实战指南与深度解析

v5版本是一个重大升级，带来了更清晰、更强大的配置模型。如果你是从旧版本迁移，需要重点关注以下变化。

7.1 配置哲学的根本转变

v4及之前版本采用的是“运行时参数驱动”模式。所有连接信息（API密钥、端点等）都通过命令行参数或环境变量在每次执行时传递。这种方式虽然灵活，但繁琐且不安全，尤其是在需要频繁切换不同LLM提供商或环境时。

v5引入了“静态配置声明”模式。所有后端及其连接信息被预先定义在一个TOML配置文件中。执行命令时，你只需要通过一个简单的后端名称（如-b azure_openai）来引用它。这带来了几个显著优势：

• 安全提升：敏感信息脱离命令行。
• 操作简化：无需记忆和输入冗长的API端点或区域参数。
• 环境管理：轻松在“开发”、“预发”、“生产”等配置间切换。

迁移操作：你需要将之前通过命令行参数（如--api-key，--aws-region）或环境变量设置的信息，整理并写入新的~/.config/aiac/aiac.toml文件。旧的调用方式将不再生效。

7.2 命令行接口的简化与统一

v4的命令行是子命令结构（aiac get ...,aiac list-models），这导致参数位置有严格要求，学习成本高。

v5将其扁平化为统一的命令结构，所有功能通过标志（flag）来控制。

• aiac list-models->aiac --list-models
• aiac get terraform for ...->aiac terraform for ...注意，get这个关键词不再是必须的，aiac会自动识别并处理你的提示词。参数位置现在更加自由。

实操对比：

# v4 方式 aiac --backend openai --api-key $KEY get terraform for ec2 # v5 方式 (假设已在配置中定义名为‘openai’的后端) aiac -b openai terraform for ec2

新的方式更简洁，更符合现代CLI工具的设计习惯。

7.3 模型管理的动态化与去硬编码

这是v5一个非常重要的底层改进。

• v4：模型列表是硬编码在aiac源码中的。添加新模型需要等待项目更新。每个后端有一个硬编码的默认模型。
• v5：模型列表通过调用后端API动态获取（使用--list-models）。默认模型由用户在配置文件中通过default_model字段自行指定。aiac不再验证模型名称的有效性，只是将其传递给API。

影响与最佳实践：

1. 责任转移：现在你需要自己确认所使用的模型名称是否正确，以及你的账户是否有权访问它。使用--list-models是了解可用模型的第一步。
2. 灵活性极大增强：你可以立即使用任何新发布的模型，只要其API兼容。例如，OpenAI发布gpt-4o-mini后，你可以直接在配置文件中将default_model改为gpt-4o-mini，无需升级aiac。
3. 配置必要性：由于没有全局硬编码默认值，你必须在配置文件中为你常用的后端设置default_model，否则在生成代码时必须每次都使用-m参数指定模型。

7.4 仅支持聊天模型的决定

v4同时支持“补全”和“聊天”两种模型。v5放弃了补全模型，只支持聊天模型。

原因深度解析：

1. 技术趋势：主流LLM提供商（OpenAI， Anthropic）已将发展重心完全转向聊天模型。补全模型（如text-davinci-003）已基本被淘汰。
2. API差异：补全模型通常需要预先指定max_tokens（生成的最大token数）。在没有模型上下文长度等元数据的情况下（v5的动态模型列表无法获取这些信息），aiac无法智能地设置这个值，容易导致生成被截断或浪费资源。聊天模型则采用更自然的“直到停止标记”的生成方式，无需指定max_tokens。
3. 用户体验：聊天模型天然支持多轮对话，这是aiac交互模式的核心基础。补全模型每次请求都是独立的，无法维持连贯的对话上下文。

对用户的影响：对于绝大多数用户而言，这个变化没有影响，因为大家早已在使用GPT-3.5-turbo或GPT-4这类聊天模型。如果你之前因某些原因在使用补全模型，现在需要切换到对应的聊天模型（例如，从text-davinci-003切换到gpt-3.5-turbo-instruct或更高版本的聊天模型）。

7.5 响应截断处理的优化

在v4中，如果API返回的响应因为达到token上限而被“截断”，aiac会将其视为错误并抛出。在实际使用中，我们发现某些提供商（或某些情况）的“停止原因”标识并不完全可靠，有时有用的内容已经生成完毕，但标记却是“length”（达到长度限制）。

v5修改了这一行为：它不再将“截断”视为错误，而是将停止原因（finish_reason）作为输出的一部分返回给用户（在库API的返回值中）。在命令行交互模式下，如果响应被截断，你可能会发现输出不完整。此时，你可以简单地输入“continue”或“go on”，让模型继续生成剩余部分。这个改动减少了因API细节差异导致的工具不可用情况，将判断权交给了用户。

从我个人的迁移经验来看，花一点时间重新编写配置文件是完全值得的。新的配置模式不仅更优雅，也为未来可能的功能扩展（如多模型负载均衡、请求缓存等）打下了更好的基础。升级后最直观的感受是命令行调用变得更简单、更一致，而动态模型列表让你能第一时间用上最新的模型。