Module @celljs/ai-pi - v4.1.0

Cell - AI pi Component

把 pi-ai 接进 Cell：pi-ai 统一了 20 多家模型服务商（Anthropic、OpenAI、Google、DeepSeek、xAI、OpenRouter、Bedrock、Ollama 等 OpenAI 兼容服务……）的调用、模型目录、凭据和用量统计。本组件提供：

PiModelsProvider：应用级的 pi-ai Models 集合，由 cell.ai.pi 配置；
PiChatModel：@celljs/ai-core 的 ChatModel 实现，经 ProxyChatModel 用 pi:<provider>/<model id> 调用；
@celljs/ai-agent 的 agent 用它取模型。

pi-ai 是 ES module 包，组件用动态 import() 加载，第一次用到模型时才加载。需要 Node.js >= 22.19 或 Bun。

配置

cell:
  ai:
    pi:
      providers: [anthropic, deepseek]   # 默认 all：注册 pi-ai 全部内置服务商
      apiKeys:                           # 只放在内存里；服务商也会读 ANTHROPIC_API_KEY 等环境变量
        deepseek: "${ env.MY_DEEPSEEK_KEY }"

兼容端点

endpoints 把 OpenAI / Anthropic 兼容的服务注册成服务商，模型名是 <端点 id>/<模型 id>：

cell:
  ai:
    pi:
      endpoints:
        local:                                  # 模型写 local/qwen3
          baseUrl: http://localhost:11434/v1    # Ollama；vLLM、LM Studio、自建网关同理
          models: [qwen3, { id: deepseek-r1, reasoning: true, contextWindow: 64000 }]
        gateway:
          baseUrl: https://llm.example.com/v1
          api: anthropic-messages               # 默认 openai-completions；还支持 openai-responses
          apiKey: "${ env.GATEWAY_KEY }"
          models: [claude-sonnet-4-5]

没有密钥的端点会收到占位密钥 no-key；apiKeys 里同名的项优先于 apiKey。

使用

import { type ChatModel, PromptTemplate, ProxyChatModel } from '@celljs/ai-core';
import { Autowired, Component } from '@celljs/core';

@Component()
export class Assistant {
    @Autowired(ProxyChatModel)
    protected readonly chatModel: ChatModel;

    @Autowired(PromptTemplate)
    protected readonly promptTemplate: PromptTemplate;

    async ask(question: string): Promise<string> {
        const prompt = await this.promptTemplate.create(question, { chatOptions: { model: 'pi:anthropic/claude-sonnet-4-5' } });
        return (await this.chatModel.call(prompt)).result.output.content;
    }
}

PiChatOptions 在 ai-core 的 ChatOptions 之外支持 reasoning（思考等级）和 tools（JSON Schema 参数的工具，模型的调用在 AssistantMessage.toolCalls 里）。stream() 每个文本增量发一个响应，最后一个响应带完整消息、结束原因（pi-ai 的 stop reason：stop、toolUse、length）和用量。模型返回错误时抛 PiModelError，模型名写错时抛 PiModelNotFoundError 并列出可用模型。

要注册自定义服务商（例如自建的 OpenAI 兼容网关），实现 PiModelsContribution，在 configure(models) 里调用 models.setProvider(...)（见 pi-ai 文档 Custom Providers）。