企业官网建设流程全解析

big-AGI 接入 Meta AI Muse 模型：OpenAI Responses 方言下的模型目录、请求契约与流式解析实践指南

【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI

Meta Model API（产品名 Meta AI，位于 dev.meta.ai）通过https://api.meta.ai/v1以 Bearer Key 方式对外提供 Muse 系列模型。在 big-AGI 中，metaai是少数几个只走 OpenAI Responses 方言的厂商之一：所有 Meta 模型统一经 Responses 适配器与解析器驱动，并拥有独立的_vnd命名空间存放厂商私有的推理连续性状态。本文以仓库知识库文档 kb/modules/LLM-metaai-responses.md 为主体，结合 chatGenerate.dispatch.ts、openai.responsesCreate.ts、openai.responses.parser.ts 与 aix.wiretypes.ts 等源码，完整拆解 Meta 模型的目录结构、请求参数边界、流式事件形态、错误与 CORS 行为，以及哪些能力被刻意排除在集成范围之外——文中所列行为均为 2026-09-02 在真实链路上实测所得，凡与官方文档冲突之处均已标注。

一、集成架构：Meta 模型为什么必须走 Responses 方言

1.1RESPONSES_ONLY_DIALECTS：只提供 Responses API 的方言集合

big-AGI 的 AIX 通信框架针对不同厂商方言进行请求分派，逻辑集中在 chatGenerate.dispatch.ts。其中定义了一个关键集合：

const RESPONSES_ONLY_DIALECTS: ReadonlySet<OpenAIDialects> = new Set<OpenAIDialects>([ 'metaai', // Meta Muse models: Responses is the only Meta surface carrying reasoning across turns 'sakanaai', 'xai', ]);

代码注释（src/modules/aix/server/dispatch/chatGenerate/chatGenerate.dispatch.ts#L36-L41）给出了 Meta 被归入该集合的直接原因：Responses 是 Meta 侧唯一能在多轮对话间携带推理状态（reasoning）的接口面。虽然 Chat Completions 与 Anthropic Messages 在api.meta.ai上同样被提供服务，但只有 Responses 方言能保留推理连续性。

分派逻辑（chatGenerate.dispatch.ts）的判断条件为：

const isResponsesAPI = !!model.vndOaiResponsesAPI || RESPONSES_ONLY_DIALECTS.has(dialect);

即：要么单个模型显式声明vndOaiResponsesAPI，要么所属方言整体只走 Responses——metaai属于后者。命中后，请求体由aixToOpenAIResponses(dialect, model, chatGenerate, streaming, enableResumability)构造，解析器则按流式/非流式分别使用createOpenAIResponsesEventParser(responsesVendor)与createOpenAIResponseParserNS(responsesVendor)。

1.2 厂商注册与密钥/主机解析

Meta AI 在厂商注册表中以ModelVendorMetaAI身份存在（src/modules/llms/vendors/metaai/metaai.vendor.ts），核心信息：

• id: 'metaai'，displayGroup: 'cloud'，instanceLimit: 1；
• 服务端下发的密钥形如LLM_<digits>_<secret>（48 字符），文档中打印的格式是LLM|<digits>|<secret>，validateSetup对两种分隔符均接受，校验规则为startsWith('LLM')且长度 ≥ 20；
• csfAvailable只在配置了密钥时为真，即支持客户端直连（CSF）模式。

密钥与主机的最终解析位于 openai.access.ts 的case 'metaai'分支：

let metaaiKey = access.oaiKey || env.METAAI_API_KEY || ''; const metaaiHost = llmsFixupHost(access.oaiHost || env.METAAI_API_HOST || DEFAULT_METAAI_HOST, apiPath); metaaiKey = llmsRandomKeyFromMultiKey(metaaiKey); if (!metaaiKey || !metaaiHost) throw new TRPCError({ code: 'BAD_REQUEST', message: 'Missing Meta AI API Key or Host...' }); return { headers: { 'Authorization': `Bearer ${metaaiKey}`, 'Content-Type': 'application/json' }, url: metaaiHost + apiPath, };

支持多密钥随机轮换（llmsRandomKeyFromMultiKey）；密钥缺失时抛出明确的BAD_REQUEST。部署侧可通过环境变量METAAI_API_KEY注入（docs/environment-variables.md 标注为可选），K8s 部署模板 docs/k8s/env-secret.yaml 亦预留了该字段。

1.3_vnd命名空间：厂商私有的推理连续性状态

metaai同时是AixWire_Vendors.RSP_VENDORS之一（aix.wiretypes.ts）：

export const RSP_VENDORS = ['metaai', 'openai', 'sakanaai', 'xai'] as const satisfies (keyof DMessageFragmentVendorStateKnown)[];

这些厂商共享 OpenAI Responses 的线上格式，但各自持有独立的_vnd命名空间用于存放连续性状态。_RspVndState_schema（aix.wiretypes.ts）定义了两种状态字段：

• reasoningItem：{ id?, encryptedContent? }——推理条目的续接句柄，对应上游输出条目中的rs_...id 与include: ['reasoning.encrypted_content']返回的加密 blob；
• phase：'commentary' | 'final_answer'——助理消息的阶段标记。

关键约束：这些 blob 是厂商服务端私有的（不同密钥、不同服务端状态），必须原路回到同一厂商才能被识别。解析器以实际厂商标签命名空间（openai.responses.parser.ts），适配器只读取自己命名空间下的 key，混用会导致 OpenAI 侧 404Item with id rs_... not found、Meta 侧 400not found or has expired之类的错误。metaai的行写入 chat.fragments.ts 的片段状态，镜像 key 保持与RSP_VENDORS同步。

二、模型目录与定价（Catalog）

GET /v1/models共返回 7 个模型 id，全部为created: 0，且不携带 type/modality 字段（因此pubDate只能走编辑性维护，参见 LLM-editorial-pubdate.md 中 Meta AI 的 Hybrid 条目）。目录结构如下：

2.1 Spark 能力与价格分层

• 上下文：1,048,576（1M）token；
• 模态：文本/图像/视频/PDF/音频均可输入（其中 1.3 的音频输入为降级状态），输出为文本；
• 标准档（Standard）定价：输入 $1.25 / 输出 $4.25 / 缓存命中 $0.15（每 1M token）；
• Contributor 定价：输入 $0.10 / 输出 $0.20 / 缓存 $0.002（每 1M token）。作为代价，Meta 会使用提示词与补全进行训练（默认隐藏该选项）。文档记录的限速为 Contributor 100 RPM / 3M TPM，Standard 3,000 RPM / 4M TPM；实测线上响应头在 Contributor id 上报告的是 150 RPM，以实测为准；
• Web 搜索：按查询计费，+$2.50 每 1K 次查询；
• Muse Image：$0.01 每张图，仅支持 aspect ratio 控制。

2.2 发布日期的编辑性维护

模型的发布属编辑性数据（Spark 1.1 发布于 2026-07-09，Muse Image 2026-07-07，1.2 于 2026-08-05，1.3 于 2026-09-02），因为 API 的created恒为 0 且官方无变更日志。模型清单与价格由内部工具/llms:update-models-metaai维护，作为元数据源。

三、请求契约：严格验证器下的参数边界

Meta 的验证器相当严格：未知的顶层参数直接 400（错误信息形如unknown parameter X），而未知的嵌套 key 则被静默忽略。为此，适配器的 zod strip 机制会在请求体上屏前剥离掉未定义字段，保证发往线上的 body 干净。以下参数在 Meta 上必然 400：seed、stop、n、logit_bias、response_format、顶层verbosity、conversation。

3.1 工具策略：只有auto

• tool_choice：仅接受auto；none、required、具名工具一律 400。big-AGI 的工具策略any在此方言下被降级为auto；
• truncation：仅接受disabled（尽管 schema 允许auto，实际发送auto会 400）。

这两条约束被固化在适配器的方言特性表_RSP_DIALECT_QUIRKS中（openai.responsesCreate.ts）：

metaai: { vndNamespace: 'metaai', toolChoiceOnlyAuto: true, minOutputTokens: 16 },

3.2 推理控制：effort 阶梯与 summary

• reasoning.effort：合法值为minimal | low | medium | high | xhigh。none能通过解析但会在每一个 Spark 模型上 400；max不在枚举中（官方预告用于 1.3）；省略时默认high——在琐碎提示词上也会消耗 95～250 个推理 token（"pong" 这类测试即如此），这是成本上需要注意的默认值；
• reasoning.summary：接受auto | concise | detailed，但返回的 summaries 经常是空数组[]，且永远没有原始推理文本（raw reasoning text）。

3.3 输出预算与不完整响应

• max_output_tokens下限为 16，适配器会做下限抬升（对应minOutputTokens: 16）；
• 推理 token 与输出共享同一预算：预算过紧时返回status: incomplete且output[]为空数组——解析层需对这种"有状态无内容"的响应做容错；
• 低于 1M 的范围内没有强制上限。

3.4 状态管理：默认无状态路径

上游默认store: true，而适配器明确发送store: false并携带include: ['reasoning.encrypted_content']，走文档化的无状态路径（推理加密内容随响应返回，而非靠服务端存储）。注意：include与previous_response_id不能同时使用，组合使用会 400。

3.5 完整接受的参数清单

实测可用的参数包括：instructions、temperature（范围 0..2；2.0 是退化值——会产出语无伦次的incomplete回复，偶尔触发 500internal server error；参数扫描记录显示 0..1.5 为可靠区间）、top_p（范围 (0,1]）、metadata（最多 16 对）、user、prompt_cache_key、safety_identifier、parallel_tool_calls、max_tool_calls、text.verbosity、service_tier（归一化为auto）。Spark 针对temperature: 1.0调优（模型定义中的initialTemperature）。

3.6 工具定义与结构化输出

• 函数工具采用扁平结构{type: 'function', name, parameters}；strict默认false——官方 schema 页面声称默认true，与实测不符，以实测为准；工具名最多含一个点；
• web_search工具接受search_context_size与user_location；适配器补充的external_web_access被容忍，但filters.allowed_domains会 400；配合include: ['web_search_call.action.sources']可让action.sources有值，解析器即读取该字段；
• 在 Spark 上使用code_interpreter、custom、image_generation工具均 400；
• 结构化输出走text.format的json_schema/json_object，仅 Responses 方言可用；
• 工具配对双向强制：未配对的function_call_output会 400，悬挂的function_call同样 400。适配器通过_pairInteriorFunctionCalls(requestInput)（openai.responsesCreate.ts）在请求侧预先补齐内部配对，否则整个请求会被整体拒绝。

四、流式协议与 items 解析

4.1 SSE 事件形态

• 事件流为 OpenAI 形状的 SSE（event:+data:行），以裸data: [DONE]结尾——这一点与 OpenAI 原生 Responses 不同（OpenAI 不发[DONE]）；执行器在收到终态事件后会忽略随后的[DONE]；
• 终态事件有三种：response.completed/response.incomplete/response.failed；此外顶层error事件可能出现在流中途，解析器需支持中途报错；
• response.output_text.done并不可靠（不总是发射），文本的实际收口由content_part.done/output_item.done完成；
• 工具循环中response.in_progress会在每一轮模型迭代重复出现（DEV 日志仅作警告，不阻断）。

4.2 并行调用与交错流

并行函数调用与 web 搜索以**交错（interleaved）**方式流出：item N+1 在 item N 关闭之前就开启。解析器的 item 访问状态机对这类失配记 DEV 日志，但能正确解码每一个调用与搜索。

4.3 推理条目（reasoning items）的特殊形态

Meta 的推理条目结构为{type, id, encrypted_content, summary, status}——没有content字段，即永远不出现明文推理文本。id 形态有两面性：

• 流式事件中的 id 是复合的：rs_<response>:rs_<inner>；
• 单次迭代（无工具循环）的response.completed.output[].id会原样重复该复合 id；
• 多轮工具循环中则退化为裸rs_<inner>。

因此id 必须按不透明句柄对待，不能做任何结构假设。两种形态均可用于续接重放（当encrypted_content存在时 id 甚至是可选的）。blob 只存活于metaai的_vnd命名空间，绝不跨厂商流动——Meta 对来自其他厂商或已过期的条目直接 400。

4.4 阶段标记与搜索失败形态

• 工具调用前的助理前置文本携带phase: 'commentary'，解析器会捕获并随重放重新发送（messagePhase状态进入_vnd命名空间，见 aix.wiretypes.ts）；
• web_search_call.action.open_page在打开失败时可能没有url（schema 已将其设为 nullish）；web 搜索条目可携带status: 'failed'。

4.5 Muse Image 的流式特例

muse-image-1.0的图像生成流不发射任何 item 事件——只有response.created直接到response.completed。big-AGI 为此模型挂载LLM_IF_HOTFIX_NoStream能力标记；非流式解析器读取image_generation_call.result（base64 WebP，由于上游不回显output_format，MIME 类型通过 base64 文件头 magic 嗅探得出）。该模型只接受image_generation一个工具。

五、错误、限流头与 CORS

5.1 错误信封

错误统一封装为{error: {code, message, param, type}}。特别要注意：验证类错误的code为 null，此时应依据type+ HTTP 状态码分支处理。各状态码语义：

5.2 限流与请求 ID 头

• x-ratelimit-{limit,remaining}-{requests,tokens}仅在Spark 生成请求上出现，限速值按团队与档位（tier）计；
• x-request-id出现在绝大多数响应上。

5.3 CORS：CSF 直连可行的关键

api.meta.ai的 CORS 配置为：

• access-control-allow-origin: *
• access-control-allow-headers: *
• access-control-allow-methods: GET,POST,DELETE,OPTIONS

预检（preflight）与错误响应都会带上这些头，因此浏览器直连（CSF）可用——这也印证了 metaai.vendor.ts 中csfAvailable的实现。但响应没有expose-headers，所以限流头在客户端侧不可见，客户端只能感知 429 与Retry-After，无法读取剩余额度。

六、刻意未接线（Deliberately not wired）

以下 Meta 能力被 big-AGI 明确排除在集成范围之外，原因如下：

1. Resume / Delete（GET/DELETE /v1/responses/{id}）：Meta 侧以与 OpenAI 完全一致的方式提供，但客户端续接杠杆全局关闭，且适配器的include门控与store: false耦合——当前的无状态路径下不启用；
2. tool_search与namespace工具、context_management/压缩条目：未实现；
3. frequency_penalty/presence_penalty：不支持；
4. prompt_cache_retention：不支持；
5. background异步执行：不支持；
6. POST /v1/responses/input_tokens：计数包含约 157 个注入的脚手架（scaffolding）token，与usage.input_tokens不可比，故不采用；
7. input_video、input_file（PDF）、input_audio部件：AIX 尚无对应的原生部件，相关附件降级为文本处理。

这些"刻意不为"同样是集成文档的价值所在——明确了当前支持边界，避免调用方误用。

七、验证与维护工具链

Meta 集成的正确性由多套工具持续校验：

• 模型清单与价格：/llms:update-models-metaai（目录与价格），模型定义的版本与选择性刷新机制参见 LLM-defs-refresh.md；
• 协议实验室：tools/develop/aix-protocol-lab提供metaai-responsesflavor（tools/develop/aix-protocol-lab/README.md），用于协议级探测；其中 engine.ts 直接以createOpenAIResponsesEventParser('metaai')/createOpenAIResponseParserNS('metaai')复用了与生产完全一致的解析器；
• 参数扫描：tools/develop/llm-parameter-sweep的metaaidialect（llm-metaai-parameters-sweep.json），配合/llms:verify-parameters metaai做参数接受度回归——temperature 0..1.5 可靠区间即来自该扫描；
• 列表测试：listModels.test.ts 内置了openai-compat/metaai: live listing用例，在存在METAAI_API_KEY时对线上目录做实测校验。

八、部署与配置要点

在 big-AGI 中使用 Meta AI 模型，按数据面（服务端 / 浏览器直连）有两种配置方式：

1. 服务端接入：在 UI 的 Models Setup 中填入metaai厂商的密钥（格式LLM_<digits>_<secret>），或通过环境变量METAAI_API_KEY（可选，见 docs/environment-variables.md）注入；可选METAAI_API_HOST覆盖默认主机。密钥缺失时服务端抛出BAD_REQUEST（"Missing Meta AI API Key or Host..."）；
2. CSF 直连（浏览器端）：由于 CORS 头允许*且预检与错误响应均携带，客户端可直接从浏览器向api.meta.ai发请求，无需服务端代理——此时限流头因缺少expose-headers对页面不可见。

使用注意清单（面向调用方）：

• 不要把tool_choice设为none/required/具名工具，Meta 只接受auto；
• 不要把truncation设为auto；
• reasoning.effort不要传none/max；默认high在琐碎请求上也会产生可观推理开销；
• max_output_tokens至少 16，且推理与输出共享预算——预算过紧会得到空output[]的incomplete响应；
• include与previous_response_id不可同用；
• temperature控制在 0..1.5 可靠区间，避开 2.0 退化区；
• 推理条目 id 一律视为不透明句柄，跨厂商复用会在 Meta 侧 400。

上述结论均来自 2026-09-02 的线上实测与当前仓库源码交叉验证；如需从零新增此类厂商接入，可参考 LLM-vendor-integration.md 中"Responses 方言厂商还需补充_RSP_DIALECT_QUIRKS行 + 专属_vnd命名空间"的完整流程。

【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI