diff --git a/content/docs/configure/ai.de.mdx b/content/docs/configure/ai.de.mdx deleted file mode 100644 index 24b17de..0000000 --- a/content/docs/configure/ai.de.mdx +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: AI-Service -description: LLMs, Embedder, RAG und MCP — providerübergreifend einsteckbar, zur Laufzeit austauschbar. -translation: - source_sha: 1b89f2c7f43c0a3ac7a72c4fe461f58764838f7d48072dda6395534452731230 - guide_rev: 1 - mode: auto ---- - -ObjectOS behandelt AI als erstklassige Fähigkeit mit **drei einsteckbaren -Schichten**: - -| Schicht | Paket | Funktion | -|---|---|---| -| **Chat / Generierung** | `@objectstack/service-ai` | Konversationen, Tool-Calls, Streaming | -| **Embeddings** | `@objectstack/embedder-openai` (OpenAI-kompatibel) | Text → Vektoren für semantische Suche und RAG | -| **Wissen / RAG** | `@objectstack/service-knowledge` + Adapter | Dokumente → indizierte Wissensdatenbanken | - -Alle drei sind optional, alle drei sind providerunabhängig, und alle drei -lassen sich zur Laufzeit über **Console → Configuration** neu konfigurieren -— ohne Neustart. - -## Chat / Generierung - -Angetrieben vom [Vercel AI SDK](https://ai-sdk.dev). Installieren Sie den -oder die gewünschten Provider als Peer-Dependencies: - -```bash -pnpm add @ai-sdk/openai # OpenAI -pnpm add @ai-sdk/anthropic # Claude -pnpm add @ai-sdk/google # Gemini -pnpm add @ai-sdk/gateway # AI gateway / OpenRouter / proxies -``` - -Registrieren Sie dann das AI-Service-Plugin mit einem Vercel-SDK-Adapter: - -```ts -import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai'; -import { openai } from '@ai-sdk/openai'; - -kernel.use(new AIServicePlugin({ - adapter: new VercelLLMAdapter({ model: openai('gpt-4o') }), - models: [ - { id: 'fast', provider: 'openai', model: 'gpt-4o-mini' }, - { id: 'smart', provider: 'openai', model: 'gpt-4o' }, - ], - defaultModelId: 'fast', -})); -``` - -Die `models`-Liste speist die Laufzeit-Modellregistry — sie steuert die -Auflösung des Standardmodells und die Kostenzuordnung in Traces. -Standardmäßig bindet sich das Plugin außerdem an den `ai`-Settings-Namespace -und baut den Adapter live neu auf, wenn ein Operator Provider/Anmeldedaten/Modell -in Console bearbeitet, sodass kein Neustart erforderlich ist. - -Die Provider-API-Schlüssel stammen aus den üblichen Umgebungsvariablen des -jeweiligen SDK: - -| Provider | Umgebungsvariable | -|---|---| -| OpenAI | `OPENAI_API_KEY` | -| Anthropic | `ANTHROPIC_API_KEY` | -| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | -| AI Gateway | `AI_GATEWAY_API_KEY` | - -In Console können Sie diese stattdessen als Laufzeiteinstellungen einfügen — -sie durchlaufen dieselbe Rangfolge (env > settings), aber durch die -Live-Bearbeitung ist kein Neustart nötig. - -### Den AI-Service aus dem Code verwenden - -```ts -const ai = kernel.getService('ai'); - -// One-shot chat -const result = await ai.chat( - [{ role: 'user', content: 'Summarize ObjectStack in two sentences.' }], - { model: 'smart' }, -); - -// Structured output -const { object } = await ai.generateObject( - [{ role: 'user', content: 'Classify this ticket: ...' }], - { schema, model: 'fast' }, -); -``` - -Der Service stellt außerdem `complete()`, `streamChat()`, `embed()` und -`listModels()` bereit. Konversationen werden als `ai_conversations` / -`ai_messages` Datensätze persistiert und über die REST-API verwaltet -(`POST /api/v1/ai/chat`, `POST /api/v1/ai/conversations`). - -### Verwendung aus Agents und Flows - -Für deklarative AI — Agents, Skills und Tools — siehe -[AI Agents](/docs/build/agents). Flows können jede registrierte Aktion -aufrufen (einschließlich Aktionen, die einen `ai.chat()`- / `ai.generateObject()`-Aufruf -kapseln) als `action`-Knoten; siehe [Flows & Automation](/docs/build/automation/flows) -für den umgebenden Kontext. - -## Embedder - -Der Embedder wandelt Text in dichte Vektoren um. Ein einziger -OpenAI-kompatibler Adapter, `@objectstack/embedder-openai`, deckt OpenAI -sowie jeden Provider ab, der einen OpenAI-kompatiblen `/v1/embeddings`-Endpunkt -bereitstellt — wählen Sie einen mit einem **Preset** (das die Basis-URL für -Sie setzt) oder verweisen Sie `baseUrl` auf einen eigenen Endpunkt. - -| Provider | `preset` | Hinweise | -|---|---|---| -| OpenAI | `openai` | `text-embedding-3-small`/`-large` | -| Azure OpenAI | `azure` | Vollständige Deployment-URL über `baseUrl` angeben | -| 阿里通义 DashScope | `dashscope` | `text-embedding-v3` | -| 智谱 GLM | `zhipu` | `embedding-2` | -| 硅基流动 SiliconFlow | `siliconflow` | Aggregator von OSS-Modellen | -| 火山 Doubao | `doubao` | ByteDance | -| MiniMax | `minimax` | — | -| Ollama (selbst gehostet) | `ollama` | Air-Gap-freundlich (`http://localhost:11434/v1`) | -| Custom | _(weglassen; `baseUrl` setzen)_ | Eigenen OpenAI-kompatiblen Endpunkt mitbringen | - -Im Code konfigurieren: - -```ts -import { createOpenAIEmbedder } from '@objectstack/embedder-openai'; - -const embedder = createOpenAIEmbedder({ - preset: 'openai', - model: 'text-embedding-3-small', - // apiKey from OPENAI_API_KEY env if omitted -}); -``` - -Oder zur Laufzeit über **Console → Configuration → AI → Embedder** auswählen. -Wechseln Sie Provider ohne Neustart; vorhandene Vektoren bleiben durchsuchbar -(Sie können im Hintergrund neu indizieren). - -## Wissen / RAG - -Der Knowledge-Service orchestriert die Dokumentenaufnahme, das Chunking, -das Embedding (über den Embedder-Service) und die Abfrage. Das eigentliche -Speicher- und Such-Backend ist einsteckbar: - -| Adapter | Backend | Geeignet für | -|---|---|---| -| `@objectstack/knowledge-memory` | In-Process | Entwicklung, Demos, kleine KBs | -| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | Hochwertiges OSS-RAG mit Chunking + Reranking | - -```ts -import { KnowledgeServicePlugin } from '@objectstack/service-knowledge'; -import { KnowledgeRagflowPlugin } from '@objectstack/knowledge-ragflow'; - -kernel.use(new KnowledgeServicePlugin({ defaultTopK: 10 })); -kernel.use(new KnowledgeRagflowPlugin({ - endpoint: process.env.RAGFLOW_ENDPOINT, // e.g. http://localhost:9380 - apiKey: process.env.RAGFLOW_API_KEY, -})); -``` - -Indizierte Wissensdatenbanken werden zu erstklassigen Objekten — fragen Sie -sie aus Flows ab, machen Sie sie in Console sichtbar, hängen Sie sie als -Retrieval-Kontext an AI-Assistenten an. - -## MCP — Model Context Protocol - -ObjectOS kann sich selbst als Tool-Server für AI-Agents (Claude Desktop, -IDEs, eigene Agents) über das offene [Model Context -Protocol](https://modelcontextprotocol.io) bereitstellen. - -```ts -import { MCPServerPlugin } from '@objectstack/mcp'; - -kernel.use(new MCPServerPlugin({ - transport: 'stdio', // or 'http' - autoStart: true, -})); -``` - -Agents entdecken und rufen ObjectOS-Tools über MCP auf — abhängig von den -Berechtigungen des aufrufenden Benutzers. Der Server überbrückt die -Tool-Registry des AI-Service, einschließlich universeller Tools wie -`list_objects`, `describe_object`, `query_records`, `get_record` und -`aggregate_data`. - -## Betriebsgarantien - -- **Keine zwingende Cloud-Abhängigkeit.** Verwenden Sie Ollama für Chat + - Ollama-Embedder + Memory-Knowledge — vollständig air-gapped. -- **Live austauschbar.** Ändern Sie den Provider in Console; neue Anfragen - nutzen den neuen Provider beim nächsten Aufruf. Kein Neustart. -- **Konfiguration pro Mandant.** Jede Environment hat ihre eigenen - AI-Einstellungen. Mandant A auf OpenAI, Mandant B auf Anthropic — dieselbe - Laufzeit. -- **Audit-Log-Einträge.** Jede Konversation, jeder Tool-Call und jede - Embedder-Anfrage kann auditiert werden (`@objectstack/plugin-audit`). -- **Kostenbewusst.** Token-Zahlen und Provider-IDs fließen in das Audit-Log - für Chargeback / Kostenanalyse. - -## Wie es weitergeht - -- [AI Agents](/docs/build/agents) — deklarative Agents, Skills und Tools -- [Flows & Automation](/docs/build/automation/flows) — AI aus deklarativer Geschäftslogik aufrufen -- [Marketplace](/docs/build/marketplace) — AI-gestützte Apps im Standardkatalog -- [Security & Compliance](/docs/reference/security) — wie AI-Datenflüsse isoliert werden -- [`@objectstack/service-ai` Quellcode](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-ai) -- [`@objectstack/embedder-openai` Quellcode](https://github.com/objectstack-ai/objectstack/tree/main/packages/plugins/embedder-openai) -- [`@objectstack/service-knowledge` Quellcode](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-knowledge) diff --git a/content/docs/configure/ai.es.mdx b/content/docs/configure/ai.es.mdx deleted file mode 100644 index 331258b..0000000 --- a/content/docs/configure/ai.es.mdx +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Servicio de IA -description: LLMs, generadores de embeddings, RAG y MCP — conectables entre proveedores, intercambiables en tiempo de ejecución. -translation: - source_sha: 1b89f2c7f43c0a3ac7a72c4fe461f58764838f7d48072dda6395534452731230 - guide_rev: 1 - mode: auto ---- - -ObjectOS trata la IA como una capacidad de primera clase con **tres capas -conectables**: - -| Capa | Paquete | Qué hace | -|---|---|---| -| **Chat / generación** | `@objectstack/service-ai` | Conversaciones, llamadas a herramientas, streaming | -| **Embeddings** | `@objectstack/embedder-openai` (compatible con OpenAI) | Texto → vectores para búsqueda semántica y RAG | -| **Conocimiento / RAG** | `@objectstack/service-knowledge` + adaptador | Documentos → bases de conocimiento indexadas | - -Las tres son opcionales, las tres son independientes del proveedor y las -tres pueden reconfigurarse en tiempo de ejecución desde **Console → -Configuration** sin necesidad de reiniciar. - -## Chat / generación - -Impulsado por el [Vercel AI SDK](https://ai-sdk.dev). Instala el o los -proveedores que quieras como peer deps: - -```bash -pnpm add @ai-sdk/openai # OpenAI -pnpm add @ai-sdk/anthropic # Claude -pnpm add @ai-sdk/google # Gemini -pnpm add @ai-sdk/gateway # AI gateway / OpenRouter / proxies -``` - -Luego registra el plugin del servicio de IA con un adaptador del Vercel-SDK: - -```ts -import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai'; -import { openai } from '@ai-sdk/openai'; - -kernel.use(new AIServicePlugin({ - adapter: new VercelLLMAdapter({ model: openai('gpt-4o') }), - models: [ - { id: 'fast', provider: 'openai', model: 'gpt-4o-mini' }, - { id: 'smart', provider: 'openai', model: 'gpt-4o' }, - ], - defaultModelId: 'fast', -})); -``` - -La lista `models` alimenta el registro de modelos en tiempo de ejecución — -impulsa la resolución del modelo predeterminado y la atribución de costos -en las trazas. De forma predeterminada, el plugin también se vincula al -espacio de nombres de configuración `ai` y reconstruye el adaptador en vivo -cuando un operador edita el proveedor/credenciales/modelo en Console, por lo -que no se necesita reiniciar. - -Las claves de API de cada proveedor provienen de las variables de entorno -habituales de cada SDK: - -| Proveedor | Variable de entorno | -|---|---| -| OpenAI | `OPENAI_API_KEY` | -| Anthropic | `ANTHROPIC_API_KEY` | -| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | -| AI Gateway | `AI_GATEWAY_API_KEY` | - -En Console puedes pegarlas como ajustes en tiempo de ejecución en su lugar — -pasan por la misma precedencia (env > settings), pero la edición en vivo -significa que no hay reinicio. - -### Uso del servicio de IA desde el código - -```ts -const ai = kernel.getService('ai'); - -// One-shot chat -const result = await ai.chat( - [{ role: 'user', content: 'Summarize ObjectStack in two sentences.' }], - { model: 'smart' }, -); - -// Structured output -const { object } = await ai.generateObject( - [{ role: 'user', content: 'Classify this ticket: ...' }], - { schema, model: 'fast' }, -); -``` - -El servicio también expone `complete()`, `streamChat()`, `embed()` y -`listModels()`. Las conversaciones se persisten como registros -`ai_conversations` / `ai_messages` y se gestionan a través de la API REST -(`POST /api/v1/ai/chat`, `POST /api/v1/ai/conversations`). - -### Uso desde agents y flows - -Para IA declarativa — agents, skills y herramientas — consulta -[AI Agents](/docs/build/agents). Los flows pueden invocar cualquier acción -registrada (incluidas las acciones que envuelven una llamada a -`ai.chat()` / `ai.generateObject()`) como un nodo `action`; consulta -[Flows & Automation](/docs/build/automation/flows) para el contexto que lo rodea. - -## Embedders - -El embedder convierte texto en vectores densos. Un único adaptador -compatible con OpenAI, `@objectstack/embedder-openai`, cubre OpenAI más -cualquier proveedor que exponga un endpoint `/v1/embeddings` compatible con -OpenAI — elige uno con un **preset** (que establece la URL base por ti) o -apunta `baseUrl` a un endpoint personalizado. - -| Proveedor | `preset` | Notas | -|---|---|---| -| OpenAI | `openai` | `text-embedding-3-small`/`-large` | -| Azure OpenAI | `azure` | Proporciona la URL de despliegue completa mediante `baseUrl` | -| 阿里通义 DashScope | `dashscope` | `text-embedding-v3` | -| 智谱 GLM | `zhipu` | `embedding-2` | -| 硅基流动 SiliconFlow | `siliconflow` | Agregador de modelos OSS | -| 火山 Doubao | `doubao` | ByteDance | -| MiniMax | `minimax` | — | -| Ollama (autoalojado) | `ollama` | Apto para entornos aislados (`http://localhost:11434/v1`) | -| Personalizado | _(omítelo; establece `baseUrl`)_ | Usa tu propio endpoint compatible con OpenAI | - -Configurar en código: - -```ts -import { createOpenAIEmbedder } from '@objectstack/embedder-openai'; - -const embedder = createOpenAIEmbedder({ - preset: 'openai', - model: 'text-embedding-3-small', - // apiKey from OPENAI_API_KEY env if omitted -}); -``` - -O elige en tiempo de ejecución desde **Console → Configuration → AI → -Embedder**. Cambia de proveedor sin reiniciar; los vectores existentes -siguen siendo consultables (puedes reindexar en segundo plano). - -## Conocimiento / RAG - -El servicio de conocimiento orquesta la ingesta de documentos, el chunking, -la generación de embeddings (a través del servicio de embedder) y la -recuperación. El backend real de almacenamiento y búsqueda es conectable: - -| Adaptador | Backend | Adecuado para | -|---|---|---| -| `@objectstack/knowledge-memory` | En proceso | Desarrollo, demos, KBs pequeñas | -| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | RAG OSS de alta calidad con chunking + reranking | - -```ts -import { KnowledgeServicePlugin } from '@objectstack/service-knowledge'; -import { KnowledgeRagflowPlugin } from '@objectstack/knowledge-ragflow'; - -kernel.use(new KnowledgeServicePlugin({ defaultTopK: 10 })); -kernel.use(new KnowledgeRagflowPlugin({ - endpoint: process.env.RAGFLOW_ENDPOINT, // e.g. http://localhost:9380 - apiKey: process.env.RAGFLOW_API_KEY, -})); -``` - -Las bases de conocimiento indexadas se convierten en objetos de primera -clase — consúltalas desde flows, muéstralas en Console, adjúntalas a -asistentes de IA como contexto de recuperación. - -## MCP — Model Context Protocol - -ObjectOS puede exponerse a sí mismo como un servidor de herramientas para -agentes de IA (Claude Desktop, IDEs, agentes personalizados) a través del -[Model Context Protocol](https://modelcontextprotocol.io) abierto. - -```ts -import { MCPServerPlugin } from '@objectstack/mcp'; - -kernel.use(new MCPServerPlugin({ - transport: 'stdio', // or 'http' - autoStart: true, -})); -``` - -Los agentes descubren e invocan las herramientas de ObjectOS a través de MCP -— sujeto a los permisos del usuario que las llama. El servidor conecta el -registro de herramientas del servicio de IA, incluidas herramientas -universales como `list_objects`, `describe_object`, `query_records`, -`get_record` y `aggregate_data`. - -## Garantías operativas - -- **Sin dependencia obligatoria de la nube.** Usa Ollama para chat + el - embedder de Ollama + conocimiento en memoria — totalmente aislado. -- **Intercambiable en vivo.** Cambia de proveedor en Console; las nuevas - solicitudes usan el nuevo proveedor en la siguiente llamada. Sin reinicio. -- **Configuración por tenant.** Cada Environment tiene sus propios ajustes - de IA. Tenant A en OpenAI, tenant B en Anthropic — el mismo runtime. -- **Entradas en el registro de auditoría.** Cada conversación, llamada a - herramienta y solicitud al embedder puede auditarse - (`@objectstack/plugin-audit`). -- **Consciente del costo.** Los recuentos de tokens y los IDs de proveedor - fluyen hacia el registro de auditoría para el chargeback / análisis de - costos. - -## Adónde ir después - -- [AI Agents](/docs/build/agents) — agents, skills y herramientas declarativos -- [Flows & Automation](/docs/build/automation/flows) — invoca la IA desde lógica de negocio declarativa -- [Marketplace](/docs/build/marketplace) — aplicaciones impulsadas por IA en el catálogo predeterminado -- [Security & Compliance](/docs/reference/security) — cómo se aíslan los flujos de datos de IA -- [Código fuente de `@objectstack/service-ai`](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-ai) -- [Código fuente de `@objectstack/embedder-openai`](https://github.com/objectstack-ai/objectstack/tree/main/packages/plugins/embedder-openai) -- [Código fuente de `@objectstack/service-knowledge`](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-knowledge) diff --git a/content/docs/configure/ai.fr.mdx b/content/docs/configure/ai.fr.mdx deleted file mode 100644 index 2cb0a14..0000000 --- a/content/docs/configure/ai.fr.mdx +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: Service IA -description: LLM, embedders, RAG et MCP — enfichables selon les fournisseurs, interchangeables à l'exécution. -translation: - source_sha: 1b89f2c7f43c0a3ac7a72c4fe461f58764838f7d48072dda6395534452731230 - guide_rev: 1 - mode: auto ---- - -ObjectOS traite l'IA comme une capacité de première classe avec **trois -couches enfichables** : - -| Couche | Package | Rôle | -|---|---|---| -| **Chat / génération** | `@objectstack/service-ai` | Conversations, appels d'outils, streaming | -| **Embeddings** | `@objectstack/embedder-openai` (compatible OpenAI) | Texte → vecteurs pour la recherche sémantique et le RAG | -| **Connaissance / RAG** | `@objectstack/service-knowledge` + adaptateur | Documents → bases de connaissances indexées | - -Les trois couches sont optionnelles, toutes les trois sont agnostiques -vis-à-vis du fournisseur, et toutes les trois peuvent être reconfigurées -à l'exécution depuis **Console → Configuration** sans redémarrage. - -## Chat / génération - -Propulsé par le [Vercel AI SDK](https://ai-sdk.dev). Installez le ou les -fournisseurs souhaités en tant que peer deps : - -```bash -pnpm add @ai-sdk/openai # OpenAI -pnpm add @ai-sdk/anthropic # Claude -pnpm add @ai-sdk/google # Gemini -pnpm add @ai-sdk/gateway # AI gateway / OpenRouter / proxies -``` - -Enregistrez ensuite le plugin du service IA avec un adaptateur Vercel-SDK : - -```ts -import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai'; -import { openai } from '@ai-sdk/openai'; - -kernel.use(new AIServicePlugin({ - adapter: new VercelLLMAdapter({ model: openai('gpt-4o') }), - models: [ - { id: 'fast', provider: 'openai', model: 'gpt-4o-mini' }, - { id: 'smart', provider: 'openai', model: 'gpt-4o' }, - ], - defaultModelId: 'fast', -})); -``` - -La liste `models` alimente le registre de modèles à l'exécution — elle -pilote la résolution du modèle par défaut et l'attribution des coûts dans -les traces. Par défaut, le plugin se lie également à l'espace de noms de -paramètres `ai` et reconstruit l'adaptateur en direct lorsqu'un opérateur -modifie le fournisseur, les identifiants ou le modèle dans la Console, -de sorte qu'aucun redémarrage n'est nécessaire. - -Les clés d'API des fournisseurs proviennent des variables d'environnement -habituelles de chaque SDK : - -| Fournisseur | Variable d'env | -|---|---| -| OpenAI | `OPENAI_API_KEY` | -| Anthropic | `ANTHROPIC_API_KEY` | -| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | -| AI Gateway | `AI_GATEWAY_API_KEY` | - -Dans la Console, vous pouvez plutôt les coller en tant que paramètres -d'exécution — ils suivent la même priorité (env > paramètres), mais -l'édition en direct évite tout redémarrage. - -### Utiliser le service IA depuis le code - -```ts -const ai = kernel.getService('ai'); - -// One-shot chat -const result = await ai.chat( - [{ role: 'user', content: 'Summarize ObjectStack in two sentences.' }], - { model: 'smart' }, -); - -// Structured output -const { object } = await ai.generateObject( - [{ role: 'user', content: 'Classify this ticket: ...' }], - { schema, model: 'fast' }, -); -``` - -Le service expose également `complete()`, `streamChat()`, `embed()` et -`listModels()`. Les conversations sont persistées sous forme -d'enregistrements `ai_conversations` / `ai_messages` et gérées via l'API -REST (`POST /api/v1/ai/chat`, `POST /api/v1/ai/conversations`). - -### L'utiliser depuis les agents et les flux - -Pour l'IA déclarative — agents, skills et outils — consultez -[AI Agents](/docs/build/agents). Les flux peuvent invoquer n'importe -quelle action enregistrée (y compris les actions qui encapsulent un appel -`ai.chat()` / `ai.generateObject()`) en tant que nœud `action` ; voir -[Flows & Automation](/docs/build/automation/flows) pour le contexte environnant. - -## Embedders - -L'embedder convertit le texte en vecteurs denses. Un unique adaptateur -compatible OpenAI, `@objectstack/embedder-openai`, couvre OpenAI ainsi que -tout fournisseur exposant un point de terminaison `/v1/embeddings` -compatible OpenAI — choisissez-en un avec un **preset** (qui définit -l'URL de base pour vous) ou pointez `baseUrl` vers un point de terminaison -personnalisé. - -| Fournisseur | `preset` | Notes | -|---|---|---| -| OpenAI | `openai` | `text-embedding-3-small`/`-large` | -| Azure OpenAI | `azure` | Fournir l'URL de déploiement complète via `baseUrl` | -| 阿里通义 DashScope | `dashscope` | `text-embedding-v3` | -| 智谱 GLM | `zhipu` | `embedding-2` | -| 硅基流动 SiliconFlow | `siliconflow` | Agrégateur de modèles OSS | -| 火山 Doubao | `doubao` | ByteDance | -| MiniMax | `minimax` | — | -| Ollama (auto-hébergé) | `ollama` | Adapté aux environnements isolés (`http://localhost:11434/v1`) | -| Personnalisé | _(omettre ; définir `baseUrl`)_ | Apportez votre propre point de terminaison compatible OpenAI | - -Configurer dans le code : - -```ts -import { createOpenAIEmbedder } from '@objectstack/embedder-openai'; - -const embedder = createOpenAIEmbedder({ - preset: 'openai', - model: 'text-embedding-3-small', - // apiKey from OPENAI_API_KEY env if omitted -}); -``` - -Ou choisissez à l'exécution depuis **Console → Configuration → AI → -Embedder**. Changez de fournisseur sans redémarrage ; les vecteurs -existants restent interrogeables (vous pouvez réindexer en arrière-plan). - -## Connaissance / RAG - -Le service de connaissance orchestre l'ingestion de documents, le -découpage en chunks, l'embedding (via le service d'embedder) et la -récupération. Le backend réel de stockage et de recherche est enfichable : - -| Adaptateur | Backend | Idéal pour | -|---|---|---| -| `@objectstack/knowledge-memory` | En mémoire (in-process) | Développement, démos, petites bases de connaissances | -| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | RAG OSS de haute qualité avec chunking + reranking | - -```ts -import { KnowledgeServicePlugin } from '@objectstack/service-knowledge'; -import { KnowledgeRagflowPlugin } from '@objectstack/knowledge-ragflow'; - -kernel.use(new KnowledgeServicePlugin({ defaultTopK: 10 })); -kernel.use(new KnowledgeRagflowPlugin({ - endpoint: process.env.RAGFLOW_ENDPOINT, // e.g. http://localhost:9380 - apiKey: process.env.RAGFLOW_API_KEY, -})); -``` - -Les bases de connaissances indexées deviennent des objets de première -classe — interrogez-les depuis les flux, exposez-les dans la Console, -attachez-les aux assistants IA en tant que contexte de récupération. - -## MCP — Model Context Protocol - -ObjectOS peut s'exposer comme serveur d'outils aux agents IA (Claude -Desktop, IDE, agents personnalisés) via le [Model Context -Protocol](https://modelcontextprotocol.io) ouvert. - -```ts -import { MCPServerPlugin } from '@objectstack/mcp'; - -kernel.use(new MCPServerPlugin({ - transport: 'stdio', // or 'http' - autoStart: true, -})); -``` - -Les agents découvrent et invoquent les outils ObjectOS via MCP — sous -réserve des permissions de l'utilisateur appelant. Le serveur fait le pont -avec le registre d'outils du service IA, y compris les outils universels -tels que `list_objects`, `describe_object`, `query_records`, `get_record` -et `aggregate_data`. - -## Garanties opérationnelles - -- **Aucune dépendance cloud obligatoire.** Utilisez Ollama pour le chat + - l'embedder Ollama + la connaissance en mémoire — entièrement isolé du - réseau. -- **Interchangeable en direct.** Changez de fournisseur dans la Console ; - les nouvelles requêtes utilisent le nouveau fournisseur au prochain - appel. Aucun redémarrage. -- **Configuration par locataire.** Chaque Environment possède ses propres - paramètres IA. Le locataire A sur OpenAI, le locataire B sur Anthropic — - même runtime. -- **Entrées de journal d'audit.** Chaque conversation, appel d'outil et - requête d'embedder peut être audité (`@objectstack/plugin-audit`). -- **Conscient des coûts.** Le nombre de tokens et les identifiants de - fournisseur remontent jusqu'au journal d'audit pour la refacturation et - l'analyse des coûts. - -## Pour aller plus loin - -- [AI Agents](/docs/build/agents) — agents, skills et outils déclaratifs -- [Flows & Automation](/docs/build/automation/flows) — appeler l'IA depuis une logique métier déclarative -- [Marketplace](/docs/build/marketplace) — applications propulsées par l'IA dans le catalogue par défaut -- [Security & Compliance](/docs/reference/security) — comment les flux de données IA sont isolés -- [Source de `@objectstack/service-ai`](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-ai) -- [Source de `@objectstack/embedder-openai`](https://github.com/objectstack-ai/objectstack/tree/main/packages/plugins/embedder-openai) -- [Source de `@objectstack/service-knowledge`](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-knowledge) diff --git a/content/docs/configure/ai.ja.mdx b/content/docs/configure/ai.ja.mdx deleted file mode 100644 index 3722468..0000000 --- a/content/docs/configure/ai.ja.mdx +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: AI サービス -description: LLM、埋め込み、RAG、MCP — プロバイダーをまたいでプラグイン化でき、実行時に差し替え可能。 -translation: - source_sha: 1b89f2c7f43c0a3ac7a72c4fe461f58764838f7d48072dda6395534452731230 - guide_rev: 1 - mode: auto ---- - -ObjectOS は AI を第一級の機能として扱い、**3 つのプラグイン可能なレイヤー**を提供します。 - -| レイヤー | パッケージ | 役割 | -|---|---|---| -| **チャット / 生成** | `@objectstack/service-ai` | 会話、ツール呼び出し、ストリーミング | -| **埋め込み** | `@objectstack/embedder-openai`（OpenAI 互換） | テキスト → ベクトル（セマンティック検索と RAG 用） | -| **ナレッジ / RAG** | `@objectstack/service-knowledge` + アダプター | ドキュメント → インデックス化されたナレッジベース | - -3 つとも任意であり、3 つともプロバイダー非依存で、3 つとも再起動なしに **Console → Configuration** から実行時に再設定できます。 - -## チャット / 生成 - -[Vercel AI SDK](https://ai-sdk.dev) を基盤としています。必要なプロバイダーをピア依存としてインストールしてください。 - -```bash -pnpm add @ai-sdk/openai # OpenAI -pnpm add @ai-sdk/anthropic # Claude -pnpm add @ai-sdk/google # Gemini -pnpm add @ai-sdk/gateway # AI gateway / OpenRouter / proxies -``` - -次に、Vercel SDK アダプターを指定して AI サービスプラグインを登録します。 - -```ts -import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai'; -import { openai } from '@ai-sdk/openai'; - -kernel.use(new AIServicePlugin({ - adapter: new VercelLLMAdapter({ model: openai('gpt-4o') }), - models: [ - { id: 'fast', provider: 'openai', model: 'gpt-4o-mini' }, - { id: 'smart', provider: 'openai', model: 'gpt-4o' }, - ], - defaultModelId: 'fast', -})); -``` - -`models` リストは実行時のモデルレジストリに渡され、デフォルトモデルの解決やトレースにおけるコスト按分を駆動します。デフォルトでは、プラグインは `ai` 設定ネームスペースにもバインドされ、オペレーターが Console でプロバイダー / 認証情報 / モデルを編集すると、アダプターをライブで再構築します。そのため再起動は不要です。 - -プロバイダーの API キーは、各 SDK の通常の環境変数から取得されます。 - -| プロバイダー | 環境変数 | -|---|---| -| OpenAI | `OPENAI_API_KEY` | -| Anthropic | `ANTHROPIC_API_KEY` | -| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | -| AI Gateway | `AI_GATEWAY_API_KEY` | - -Console ではこれらを実行時設定として貼り付けることもできます。同じ優先順位（env > settings）に従いますが、ライブ編集なので再起動は不要です。 - -### コードから AI サービスを使う - -```ts -const ai = kernel.getService('ai'); - -// One-shot chat -const result = await ai.chat( - [{ role: 'user', content: 'Summarize ObjectStack in two sentences.' }], - { model: 'smart' }, -); - -// Structured output -const { object } = await ai.generateObject( - [{ role: 'user', content: 'Classify this ticket: ...' }], - { schema, model: 'fast' }, -); -``` - -このサービスは `complete()`、`streamChat()`、`embed()`、`listModels()` も公開しています。会話は `ai_conversations` / `ai_messages` レコードとして永続化され、REST API（`POST /api/v1/ai/chat`、`POST /api/v1/ai/conversations`）経由で管理されます。 - -### エージェントとフローから使う - -宣言的な AI — エージェント、スキル、ツール — については [AI Agents](/docs/build/agents) を参照してください。フローは、登録済みの任意のアクション（`ai.chat()` / `ai.generateObject()` 呼び出しをラップするアクションを含む）を `action` ノードとして呼び出せます。周辺の文脈については [Flows & Automation](/docs/build/automation/flows) を参照してください。 - -## 埋め込み（Embedders） - -埋め込みはテキストを密ベクトルに変換します。単一の OpenAI 互換アダプター `@objectstack/embedder-openai` は、OpenAI に加えて、OpenAI 互換の `/v1/embeddings` エンドポイントを公開するあらゆるプロバイダーをカバーします。**プリセット**（ベースURLを自動設定します）を選ぶか、`baseUrl` をカスタムエンドポイントに向けてください。 - -| プロバイダー | `preset` | 備考 | -|---|---|---| -| OpenAI | `openai` | `text-embedding-3-small`/`-large` | -| Azure OpenAI | `azure` | `baseUrl` で完全なデプロイメント URL を指定 | -| 阿里通义 DashScope | `dashscope` | `text-embedding-v3` | -| 智谱 GLM | `zhipu` | `embedding-2` | -| 硅基流动 SiliconFlow | `siliconflow` | OSS モデルのアグリゲーター | -| 火山 Doubao | `doubao` | ByteDance | -| MiniMax | `minimax` | — | -| Ollama（セルフホスト） | `ollama` | エアギャップ環境に対応（`http://localhost:11434/v1`） | -| カスタム | _(省略し、`baseUrl` を設定)_ | 独自の OpenAI 互換エンドポイントを使用 | - -コードでの設定: - -```ts -import { createOpenAIEmbedder } from '@objectstack/embedder-openai'; - -const embedder = createOpenAIEmbedder({ - preset: 'openai', - model: 'text-embedding-3-small', - // apiKey from OPENAI_API_KEY env if omitted -}); -``` - -または **Console → Configuration → AI → Embedder** から実行時に選択します。再起動なしでプロバイダーを切り替えても、既存のベクトルは検索可能なまま残ります（バックグラウンドで再インデックスできます）。 - -## ナレッジ / RAG - -ナレッジサービスは、ドキュメントの取り込み、チャンク分割、埋め込み（embedder サービス経由）、検索をオーケストレーションします。実際のストレージと検索のバックエンドはプラグイン可能です。 - -| アダプター | バックエンド | 適した用途 | -|---|---|---| -| `@objectstack/knowledge-memory` | インプロセス | 開発、デモ、小規模な KB | -| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | チャンク分割 + リランキングを備えた高品質な OSS RAG | - -```ts -import { KnowledgeServicePlugin } from '@objectstack/service-knowledge'; -import { KnowledgeRagflowPlugin } from '@objectstack/knowledge-ragflow'; - -kernel.use(new KnowledgeServicePlugin({ defaultTopK: 10 })); -kernel.use(new KnowledgeRagflowPlugin({ - endpoint: process.env.RAGFLOW_ENDPOINT, // e.g. http://localhost:9380 - apiKey: process.env.RAGFLOW_API_KEY, -})); -``` - -インデックス化されたナレッジベースは第一級のオブジェクトになります。フローからクエリしたり、Console に表示したり、検索コンテキストとして AI アシスタントに紐付けたりできます。 - -## MCP — Model Context Protocol - -ObjectOS は、オープンな [Model Context Protocol](https://modelcontextprotocol.io) を介して、AI エージェント（Claude Desktop、IDE、カスタムエージェント）に対してツールサーバーとして自身を公開できます。 - -```ts -import { MCPServerPlugin } from '@objectstack/mcp'; - -kernel.use(new MCPServerPlugin({ - transport: 'stdio', // or 'http' - autoStart: true, -})); -``` - -エージェントは MCP を通じて ObjectOS のツールを検出し呼び出します — 呼び出しユーザーの権限に従います。サーバーは AI サービスのツールレジストリをブリッジし、`list_objects`、`describe_object`、`query_records`、`get_record`、`aggregate_data` などの汎用ツールを含みます。 - -## 運用上の保証 - -- **クラウド依存を必須としない。** チャットに Ollama、埋め込みに Ollama embedder、ナレッジに memory を使えば、完全なエアギャップ運用が可能です。 -- **ライブで差し替え可能。** Console でプロバイダーを変更すると、次の呼び出しから新しいリクエストが新しいプロバイダーを使用します。再起動は不要です。 -- **テナントごとの設定。** 各 Environment は独自の AI 設定を持ちます。テナント A は OpenAI、テナント B は Anthropic — 同一ランタイムで実現できます。 -- **監査ログの記録。** すべての会話、ツール呼び出し、embedder リクエストを監査できます（`@objectstack/plugin-audit`）。 -- **コストを意識。** トークン数とプロバイダー ID は監査ログに流れ、チャージバックやコスト分析に利用できます。 - -## 次に読むべきもの - -- [AI Agents](/docs/build/agents) — 宣言的なエージェント、スキル、ツール -- [Flows & Automation](/docs/build/automation/flows) — 宣言的なビジネスロジックから AI を呼び出す -- [Marketplace](/docs/build/marketplace) — デフォルトカタログに含まれる AI 搭載アプリ -- [Security & Compliance](/docs/reference/security) — AI のデータフローがどのように隔離されるか -- [`@objectstack/service-ai` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-ai) -- [`@objectstack/embedder-openai` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/plugins/embedder-openai) -- [`@objectstack/service-knowledge` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-knowledge) diff --git a/content/docs/configure/ai.ko.mdx b/content/docs/configure/ai.ko.mdx deleted file mode 100644 index 3002c30..0000000 --- a/content/docs/configure/ai.ko.mdx +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: AI 서비스 -description: LLM, 임베더, RAG, MCP — 여러 공급자 간에 교체 가능하며 런타임에 전환할 수 있습니다. -translation: - source_sha: 1b89f2c7f43c0a3ac7a72c4fe461f58764838f7d48072dda6395534452731230 - guide_rev: 1 - mode: auto ---- - -ObjectOS는 AI를 **세 가지 교체 가능한 계층**으로 구성된 일급 기능으로 취급합니다: - -| 계층 | 패키지 | 역할 | -|---|---|---| -| **채팅 / 생성** | `@objectstack/service-ai` | 대화, 도구 호출, 스트리밍 | -| **임베딩** | `@objectstack/embedder-openai` (OpenAI 호환) | 텍스트 → 벡터, 시맨틱 검색 및 RAG용 | -| **지식 / RAG** | `@objectstack/service-knowledge` + 어댑터 | 문서 → 인덱싱된 지식 베이스 | - -세 계층 모두 선택 사항이며, 모두 공급자에 종속되지 않고, 모두 **Console → Configuration**에서 재시작 없이 런타임에 재구성할 수 있습니다. - -## 채팅 / 생성 - -[Vercel AI SDK](https://ai-sdk.dev)로 구동됩니다. 원하는 공급자를 peer 의존성으로 설치하세요: - -```bash -pnpm add @ai-sdk/openai # OpenAI -pnpm add @ai-sdk/anthropic # Claude -pnpm add @ai-sdk/google # Gemini -pnpm add @ai-sdk/gateway # AI gateway / OpenRouter / proxies -``` - -그런 다음 Vercel-SDK 어댑터와 함께 AI 서비스 플러그인을 등록합니다: - -```ts -import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai'; -import { openai } from '@ai-sdk/openai'; - -kernel.use(new AIServicePlugin({ - adapter: new VercelLLMAdapter({ model: openai('gpt-4o') }), - models: [ - { id: 'fast', provider: 'openai', model: 'gpt-4o-mini' }, - { id: 'smart', provider: 'openai', model: 'gpt-4o' }, - ], - defaultModelId: 'fast', -})); -``` - -`models` 목록은 런타임 모델 레지스트리에 입력됩니다 — 이는 기본 모델 해석과 트레이스 내 비용 귀속을 주도합니다. 기본적으로 플러그인은 `ai` 설정 네임스페이스에도 바인딩되며, 운영자가 Console에서 공급자/자격 증명/모델을 편집하면 어댑터를 실시간으로 다시 빌드하므로 재시작이 필요하지 않습니다. - -공급자 API 키는 각 SDK의 일반 환경 변수에서 가져옵니다: - -| 공급자 | 환경 변수 | -|---|---| -| OpenAI | `OPENAI_API_KEY` | -| Anthropic | `ANTHROPIC_API_KEY` | -| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | -| AI Gateway | `AI_GATEWAY_API_KEY` | - -Console에서는 이 값들을 런타임 설정으로 붙여넣을 수도 있습니다 — 동일한 우선순위(env > settings)를 따르지만, 실시간 편집이 가능하므로 재시작이 필요 없습니다. - -### 코드에서 AI 서비스 사용하기 - -```ts -const ai = kernel.getService('ai'); - -// One-shot chat -const result = await ai.chat( - [{ role: 'user', content: 'Summarize ObjectStack in two sentences.' }], - { model: 'smart' }, -); - -// Structured output -const { object } = await ai.generateObject( - [{ role: 'user', content: 'Classify this ticket: ...' }], - { schema, model: 'fast' }, -); -``` - -이 서비스는 `complete()`, `streamChat()`, `embed()`, `listModels()`도 노출합니다. 대화는 `ai_conversations` / `ai_messages` 레코드로 영속화되며 REST API(`POST /api/v1/ai/chat`, `POST /api/v1/ai/conversations`)를 통해 관리됩니다. - -### 에이전트와 플로우에서 사용하기 - -선언적 AI — 에이전트, 스킬, 도구 — 에 대해서는 [AI Agents](/docs/build/agents)를 참고하세요. 플로우는 등록된 모든 액션(`ai.chat()` / `ai.generateObject()` 호출을 감싸는 액션 포함)을 `action` 노드로 호출할 수 있습니다. 주변 맥락은 [Flows & Automation](/docs/build/automation/flows)을 참고하세요. - -## 임베더 - -임베더는 텍스트를 밀집 벡터로 변환합니다. 단일 OpenAI 호환 어댑터인 `@objectstack/embedder-openai`는 OpenAI는 물론 OpenAI 호환 `/v1/embeddings` 엔드포인트를 노출하는 모든 공급자를 지원합니다 — **preset**으로 하나를 선택하거나(이 경우 base URL이 자동 설정됨), `baseUrl`을 사용자 정의 엔드포인트로 지정하세요. - -| 공급자 | `preset` | 비고 | -|---|---|---| -| OpenAI | `openai` | `text-embedding-3-small`/`-large` | -| Azure OpenAI | `azure` | `baseUrl`로 전체 배포 URL 제공 | -| 阿里通义 DashScope | `dashscope` | `text-embedding-v3` | -| 智谱 GLM | `zhipu` | `embedding-2` | -| 硅基流动 SiliconFlow | `siliconflow` | OSS 모델 애그리게이터 | -| 火山 Doubao | `doubao` | ByteDance | -| MiniMax | `minimax` | — | -| Ollama (자체 호스팅) | `ollama` | 오프라인(air-gapped) 환경에 적합 (`http://localhost:11434/v1`) | -| 사용자 정의 | _(생략; `baseUrl` 설정)_ | 자체 OpenAI 호환 엔드포인트 사용 | - -코드에서 구성: - -```ts -import { createOpenAIEmbedder } from '@objectstack/embedder-openai'; - -const embedder = createOpenAIEmbedder({ - preset: 'openai', - model: 'text-embedding-3-small', - // apiKey from OPENAI_API_KEY env if omitted -}); -``` - -또는 **Console → Configuration → AI → Embedder**에서 런타임에 선택하세요. 재시작 없이 공급자를 전환할 수 있으며, 기존 벡터는 계속 검색 가능합니다(백그라운드에서 다시 인덱싱할 수 있습니다). - -## 지식 / RAG - -지식 서비스는 문서 수집, 청킹, 임베딩(임베더 서비스 경유), 검색을 오케스트레이션합니다. 실제 저장 및 검색 백엔드는 교체 가능합니다: - -| 어댑터 | 백엔드 | 적합한 용도 | -|---|---|---| -| `@objectstack/knowledge-memory` | 인프로세스 | 개발, 데모, 소규모 KB | -| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | 청킹 + 리랭킹을 갖춘 고품질 OSS RAG | - -```ts -import { KnowledgeServicePlugin } from '@objectstack/service-knowledge'; -import { KnowledgeRagflowPlugin } from '@objectstack/knowledge-ragflow'; - -kernel.use(new KnowledgeServicePlugin({ defaultTopK: 10 })); -kernel.use(new KnowledgeRagflowPlugin({ - endpoint: process.env.RAGFLOW_ENDPOINT, // e.g. http://localhost:9380 - apiKey: process.env.RAGFLOW_API_KEY, -})); -``` - -인덱싱된 지식 베이스는 일급 객체가 됩니다 — 플로우에서 쿼리하고, Console에 노출하고, 검색 컨텍스트로 AI 어시스턴트에 연결할 수 있습니다. - -## MCP — Model Context Protocol - -ObjectOS는 개방형 [Model Context Protocol](https://modelcontextprotocol.io)을 통해 자신을 AI 에이전트(Claude Desktop, IDE, 사용자 정의 에이전트)에 대한 도구 서버로 노출할 수 있습니다. - -```ts -import { MCPServerPlugin } from '@objectstack/mcp'; - -kernel.use(new MCPServerPlugin({ - transport: 'stdio', // or 'http' - autoStart: true, -})); -``` - -에이전트는 MCP를 통해 ObjectOS 도구를 발견하고 호출합니다 — 호출하는 사용자의 권한이 적용됩니다. 서버는 `list_objects`, `describe_object`, `query_records`, `get_record`, `aggregate_data`와 같은 범용 도구를 포함하여 AI 서비스의 도구 레지스트리를 브리지합니다. - -## 운영 보장 - -- **필수 클라우드 의존성 없음.** 채팅에 Ollama + Ollama 임베더 + 메모리 지식을 사용하면 완전히 오프라인(air-gapped)으로 동작합니다. -- **실시간 교체 가능.** Console에서 공급자를 변경하면 새 요청은 다음 호출부터 새 공급자를 사용합니다. 재시작이 필요 없습니다. -- **테넌트별 구성.** 각 Environment는 자체 AI 설정을 가집니다. 테넌트 A는 OpenAI, 테넌트 B는 Anthropic — 동일한 런타임에서 동작합니다. -- **감사 로그 기록.** 모든 대화, 도구 호출, 임베더 요청을 감사할 수 있습니다(`@objectstack/plugin-audit`). -- **비용 인식.** 토큰 수와 공급자 ID가 감사 로그로 전달되어 비용 청구/비용 분석에 활용됩니다. - -## 다음으로 갈 곳 - -- [AI Agents](/docs/build/agents) — 선언적 에이전트, 스킬, 도구 -- [Flows & Automation](/docs/build/automation/flows) — 선언적 비즈니스 로직에서 AI 호출하기 -- [Marketplace](/docs/build/marketplace) — 기본 카탈로그의 AI 기반 앱 -- [Security & Compliance](/docs/reference/security) — AI 데이터 흐름이 격리되는 방식 -- [`@objectstack/service-ai` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-ai) -- [`@objectstack/embedder-openai` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/plugins/embedder-openai) -- [`@objectstack/service-knowledge` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-knowledge) diff --git a/content/docs/configure/ai.mdx b/content/docs/configure/ai.mdx index fe2ae32..0e357ea 100644 --- a/content/docs/configure/ai.mdx +++ b/content/docs/configure/ai.mdx @@ -1,166 +1,159 @@ --- title: AI Service -description: LLMs, embedders, RAG, and MCP — pluggable across providers, swappable at runtime. +description: Where ObjectOS's AI is configured — the in-product AI runtime's provider settings, the open embedder and knowledge packages, and the MCP server. --- -ObjectOS treats AI as a first-class capability with **three pluggable -layers**: +ObjectOS adds an **in-product AI runtime** — the `ask` data-query assistant, +the `build` authoring assistant, and the `/api/v1/ai/*` chat endpoints — on +top of AI primitives that ship in the open-source ObjectStack framework: the +MCP server, the Knowledge Protocol and its adapters, and the embedder. -| Layer | Package | What it does | -|---|---|---| -| **Chat / generation** | `@objectstack/service-ai` | Conversations, tool calls, streaming | -| **Embeddings** | `@objectstack/embedder-openai` (OpenAI-compatible) | Text → vectors for semantic search and RAG | -| **Knowledge / RAG** | `@objectstack/service-knowledge` + adapter | Documents → indexed knowledge bases | +On a Self-Managed deployment, a licence is what unlocks the in-product AI. A +single-organization deployment without one runs with Community behaviour — +the open MCP server, bring your own AI — and with one, the AI Builder and +"ask your data" are unlocked on your own infrastructure. See +[Docker → Licence](/docs/deploy/docker#licence). -All three are optional, all three are provider-agnostic, and all three -can be reconfigured at runtime from **Setup → Configuration** -without a restart. +## What is configured where -## Chat / generation +| Layer | Where it is configured | Ships in | +|---|---|---| +| **Chat model provider** | The `ai` settings namespace: **Setup → Configuration → AI & Embedder**, or `OS_AI_*` environment variables | ObjectOS | +| **Embeddings** | `@objectstack/embedder-openai`, an OpenAI-compatible embedder | Open framework | +| **Knowledge / RAG** | `@objectstack/service-knowledge` plus an adapter plugin | Open framework | +| **MCP server** | On by default at `/api/v1/mcp`; `OS_MCP_SERVER_ENABLED=false` turns it off | Open framework | -Powered by the [Vercel AI SDK](https://ai-sdk.dev). Install the -provider(s) you want as peer deps: +## Chat model provider -```bash -pnpm add @ai-sdk/openai # OpenAI -pnpm add @ai-sdk/anthropic # Claude -pnpm add @ai-sdk/google # Gemini -pnpm add @ai-sdk/gateway # AI gateway / OpenRouter / proxies -``` +There is no AI package to install or register. `@objectstack/service-ai` +left the open ObjectStack distribution in 11.0; the AI runtime it provides +ships with ObjectOS, not with the open-source framework. -Then register the AI service plugin with a Vercel-SDK adapter: +The provider, model and credentials are settings in the `ai` namespace, so +they resolve like every other setting: an environment variable wins over the +value stored in Setup, and locks it ([System Settings → Resolution order](/docs/configure/system-settings#resolution-order)). -```ts -import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai'; -import { openai } from '@ai-sdk/openai'; - -kernel.use(new AIServicePlugin({ - adapter: new VercelLLMAdapter({ model: openai('gpt-4o') }), - models: [ - { id: 'fast', provider: 'openai', model: 'gpt-4o-mini' }, - { id: 'smart', provider: 'openai', model: 'gpt-4o' }, - ], - defaultModelId: 'fast', -})); -``` +| Variable | Sets | +|---|---| +| `OS_AI_PROVIDER` | The provider. Supported values include `gateway`, `openai`, `anthropic`, `google`, `deepseek`, `dashscope`, `cloudflare`, `siliconflow`, and `openrouter`. | +| `OS_AI_OPENAI_API_KEY` · `OS_AI_OPENAI_MODEL` · `OS_AI_OPENAI_BASE_URL` | OpenAI, or any OpenAI-compatible API — Azure, a local gateway, a third-party endpoint — with `OS_AI_PROVIDER=openai`. The model defaults to `gpt-4o`. | +| `OS_AI_ANTHROPIC_API_KEY` · `OS_AI_ANTHROPIC_MODEL` | Anthropic, with `OS_AI_PROVIDER=anthropic`. | +| `OS_AI_GOOGLE_API_KEY` · `OS_AI_GOOGLE_MODEL` | Google, with `OS_AI_PROVIDER=google`. | +| `OS_AI_GATEWAY_MODEL` · `OS_AI_GATEWAY_API_KEY` | Vercel AI Gateway, with `OS_AI_PROVIDER=gateway`. | +| `OS_AI_DEEPSEEK_API_KEY`, `OS_AI_DASHSCOPE_API_KEY`, … | One `_API_KEY` and one `_MODEL` variable per preset OpenAI-compatible provider, for example `OS_AI_DEEPSEEK_MODEL=deepseek-chat`. | -The `models` list feeds the runtime model registry — it drives -default-model resolution and cost attribution in traces. By default the -plugin also binds to the `ai` settings namespace and rebuilds the -adapter live when an operator edits the provider/credentials/model in -Setup, so no restart is needed. +For example, to lock a third-party OpenAI-compatible provider for the whole +deployment without using Setup: -Provider API keys come from each SDK's normal env vars: +```bash +OS_AI_PROVIDER=openai +OS_AI_OPENAI_API_KEY=sk-... +OS_AI_OPENAI_MODEL=your-model +OS_AI_OPENAI_BASE_URL=https://your-provider.example.com/v1 +``` -| Provider | Env var | -|---|---| -| OpenAI | `OPENAI_API_KEY` | -| Anthropic | `ANTHROPIC_API_KEY` | -| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | -| AI Gateway | `AI_GATEWAY_API_KEY` | +Use `OS_AI_OPENAI_BASE_URL` for an OpenAI-compatible base URL, or the same +field in Setup; `OPENAI_BASE_URL` is not a platform-level variable. -In Setup you can paste these as runtime settings instead — they go -through the same precedence (env > settings) but live editing means -no restart. +### When no provider is set -### Using the AI service from code +The runtime picks an adapter at boot from the first upstream credential it +finds: -```ts -const ai = kernel.getService('ai'); - -// One-shot chat -const result = await ai.chat( - [{ role: 'user', content: 'Summarize ObjectStack in two sentences.' }], - { model: 'smart' }, -); - -// Structured output -const { object } = await ai.generateObject( - [{ role: 'user', content: 'Classify this ticket: ...' }], - { schema, model: 'fast' }, -); -``` +1. `AI_GATEWAY_MODEL` (with `AI_GATEWAY_API_KEY`), through the Vercel AI Gateway; +2. `OPENAI_API_KEY`; +3. `ANTHROPIC_API_KEY`; +4. `GOOGLE_GENERATIVE_AI_API_KEY`; +5. none of them: `MemoryLLMAdapter`, an echo mode with no real provider behind it. -The service also exposes `complete()`, `streamChat()`, `embed()`, and -`listModels()`. Conversations are persisted as `ai_conversations` / -`ai_messages` records and managed over the REST API -(`POST /api/v1/ai/chat`, `POST /api/v1/ai/conversations`). +These keep their upstream names; they are not renamed to `OS_*`. `OS_AI_MODEL` +overrides the model id for the direct OpenAI, Anthropic and Google detection. +After boot, the runtime reads the `ai` settings namespace and swaps the +adapter when the provider comes from an environment variable or a value +stored in Setup. -### Using it from agents and flows +### Calling it -For declarative AI — agents, skills, and tools — see -[AI Agents](/docs/build/agents). Flows can invoke any registered action -(including actions that wrap an `ai.chat()` / `ai.generateObject()` -call) as an `action` node; see [Flows & Automation](/docs/build/automation/flows) -for the surrounding context. +The in-product AI is served under `/api/v1/ai/*` — chat (JSON or streaming), +completion, the models an environment offers, and conversations — and the +`@objectstack/client` SDK reaches it through its `ai` namespace: `ai.chat`, +`ai.chatStream`, `ai.complete`, `ai.models`, and `ai.conversations`. For +declarative AI — agents, skills, and tools — see [AI Agents](/docs/build/agents). ## Embedders -The embedder converts text to dense vectors. A single OpenAI-compatible -adapter, `@objectstack/embedder-openai`, covers OpenAI plus any provider -that exposes an OpenAI-compatible `/v1/embeddings` endpoint — pick one -with a **preset** (which sets the base URL for you) or point `baseUrl` -at a custom endpoint. - -| Provider | `preset` | Notes | -|---|---|---| -| OpenAI | `openai` | `text-embedding-3-small`/`-large` | -| Azure OpenAI | `azure` | Provide full deployment URL via `baseUrl` | -| 阿里通义 DashScope | `dashscope` | `text-embedding-v3` | -| 智谱 GLM | `zhipu` | `embedding-2` | -| 硅基流动 SiliconFlow | `siliconflow` | Aggregator of OSS models | -| 火山 Doubao | `doubao` | ByteDance | -| MiniMax | `minimax` | — | -| Ollama (self-hosted) | `ollama` | Air-gapped friendly (`http://localhost:11434/v1`) | -| Custom | _(omit; set `baseUrl`)_ | Bring your own OpenAI-compatible endpoint | - -Configure in code: +`@objectstack/embedder-openai` works against any endpoint that speaks the +OpenAI `POST /v1/embeddings` shape: OpenAI, Azure OpenAI, DashScope, Zhipu +BigModel, SiliconFlow, Doubao, MiniMax, Ollama, or your own gateway. A +**preset** fills in the base URL of a known provider; `baseUrl` points at any +other endpoint. ```ts import { createOpenAIEmbedder } from '@objectstack/embedder-openai'; const embedder = createOpenAIEmbedder({ - preset: 'openai', - model: 'text-embedding-3-small', - // apiKey from OPENAI_API_KEY env if omitted + preset: 'dashscope', + apiKey: process.env.DASHSCOPE_API_KEY!, + model: 'text-embedding-v3', }); ``` -Or pick at runtime from **Setup → Configuration → AI → Embedder**. -Switch providers without restart; existing vectors stay searchable -(you can re-index in the background). +`apiKey` is required. The +[package README](https://github.com/objectstack-ai/objectstack/tree/main/packages/plugins/embedder-openai) +lists the base URL and a typical model for each provider. + +No knowledge adapter in the open framework consumes an embedder yet: +`@objectstack/knowledge-memory` and `@objectstack/knowledge-ragflow` take no +embedder option. ## Knowledge / RAG -The knowledge service orchestrates document ingestion, chunking, -embedding (via the embedder service), and retrieval. The actual -storage and search backend is pluggable: +The knowledge service declares knowledge sources and filters what comes back +by permission; an adapter plugin does the retrieval itself. | Adapter | Backend | Good for | |---|---|---| -| `@objectstack/knowledge-memory` | In-process | Dev, demos, small KBs | -| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | High-quality OSS RAG with chunking + reranking | +| `@objectstack/knowledge-memory` | In-process | Dev environments and tests — not for production: no persistence | +| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | Chunking, embedding, hybrid retrieval, and reranking, done by RAGFlow | + +In the open framework the wiring is: ```ts import { KnowledgeServicePlugin } from '@objectstack/service-knowledge'; import { KnowledgeRagflowPlugin } from '@objectstack/knowledge-ragflow'; -kernel.use(new KnowledgeServicePlugin({ defaultTopK: 10 })); +kernel.use(new KnowledgeServicePlugin({ + sources: [{ + id: 'product_docs', + label: 'Product documentation', + adapter: 'ragflow', + source: { kind: 'http', urls: ['https://docs.example.com/sitemap.xml'] }, + adapterConfig: { datasetId: 'rgf_doc_dataset_id' }, // RAGFlow dataset to bind + }], +})); kernel.use(new KnowledgeRagflowPlugin({ - endpoint: process.env.RAGFLOW_ENDPOINT, // e.g. http://localhost:9380 - apiKey: process.env.RAGFLOW_API_KEY, + endpoint: process.env.RAGFLOW_ENDPOINT!, // e.g. http://localhost:9380 + apiKey: process.env.RAGFLOW_API_KEY!, })); ``` -Indexed knowledge bases become first-class objects — query them from -flows, surface them in your apps, attach them to AI assistants as -retrieval context. +The RAGFlow adapter does not create datasets: create one once in the RAGFlow +UI, where you pick the chunking method, embedding model, and rerank policy. + +Every hit that carries a source record is re-checked against the caller's +permissions — the same row-level security that gates a plain ObjectQL query. +Exposing retrieval to the in-product chat as the `search_knowledge` tool is +part of the ObjectOS runtime. ## MCP — Model Context Protocol -ObjectOS can expose itself as a tool server to AI agents (Claude -Desktop, IDEs, custom agents) via the open [Model Context -Protocol](https://modelcontextprotocol.io). +Every ObjectOS deployment already serves the +[Model Context Protocol](https://modelcontextprotocol.io) at `/api/v1/mcp` — +on by default, no plugin to install — and can serve it over stdio as well. +[Connect AI Tools (MCP)](/docs/configure/mcp) covers connecting a client, the +stdio switch, and the tools an agent gets. + +Registering the MCP server plugin explicitly, in the open framework: ```ts import { MCPServerPlugin } from '@objectstack/mcp'; @@ -171,30 +164,17 @@ kernel.use(new MCPServerPlugin({ })); ``` -Agents discover and invoke ObjectOS tools through MCP — subject to the -calling user's permissions. The server bridges the AI service's tool -registry, including universal tools such as `list_objects`, -`describe_object`, `query_records`, `get_record`, and `aggregate_data`. - -## Operational guarantees - -- **No mandatory cloud dependency.** Use Ollama for chat + Ollama - embedder + memory knowledge — entirely air-gapped. -- **Live swappable.** Change provider in Setup; new requests use the - new provider on next call. No restart. -- **Per-tenant config.** Each Environment has its own AI settings. - Tenant A on OpenAI, tenant B on Anthropic — same runtime. -- **Audit log entries.** Every conversation, tool call, and embedder - request can be audited (`@objectstack/plugin-audit`). -- **Cost-aware.** Token counts and provider IDs flow through to the - audit log for chargeback / cost analysis. +Tools are not opted into per option: the plugin bridges the AI tool +registry, the metadata service and the data engine when it starts. Every call +runs under the calling user's permissions. ## Where to go next - [AI Agents](/docs/build/agents) — declarative agents, skills, and tools -- [Flows & Automation](/docs/build/automation/flows) — call AI from declarative business logic -- [Marketplace](/docs/build/marketplace) — AI-powered apps in the default catalog +- [Connect AI Tools (MCP)](/docs/configure/mcp) — point an external client at your app +- [System Settings](/docs/configure/system-settings) — how a setting resolves, and what an environment variable locks - [Security & Compliance](/docs/reference/security) — how AI data flows are isolated -- [`@objectstack/service-ai` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-ai) - [`@objectstack/embedder-openai` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/plugins/embedder-openai) - [`@objectstack/service-knowledge` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-knowledge) +- [`@objectstack/knowledge-ragflow` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/plugins/knowledge-ragflow) +- [`@objectstack/mcp` source](https://github.com/objectstack-ai/objectstack/tree/main/packages/mcp) diff --git a/content/docs/configure/ai.zh-Hans.mdx b/content/docs/configure/ai.zh-Hans.mdx deleted file mode 100644 index e9b580a..0000000 --- a/content/docs/configure/ai.zh-Hans.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: AI 服务 -description: LLM、Embedder、RAG 与 MCP —— 多 Provider 可插拔，运行时可切换。 -translation: - source_sha: 1b89f2c7f43c0a3ac7a72c4fe461f58764838f7d48072dda6395534452731230 - guide_rev: 1 - mode: auto ---- - -ObjectOS 把 AI 视为一等能力，分为**三个可插拔层**： - -| 层 | 包 | 作用 | -|---|---|---| -| **Chat / 生成** | `@objectstack/service-ai` | 会话、工具调用、流式输出 | -| **Embeddings** | `@objectstack/service-embedder` + 适配器 | 文本 → 向量，用于语义搜索和 RAG | -| **Knowledge / RAG** | `@objectstack/service-knowledge` + 适配器 | 文档 → 已索引的知识库 | - -三层都是可选的，都是与 Provider 解耦的，并且都可以在 **Console → Configuration** 中运行时重配，无需重启。 - -## Chat / 生成 - -由 [Vercel AI SDK](https://ai-sdk.dev) 驱动。把你想用的 Provider 作为 peer 依赖安装： - -```bash -pnpm add @ai-sdk/openai # OpenAI -pnpm add @ai-sdk/anthropic # Claude -pnpm add @ai-sdk/google # Gemini -pnpm add @ai-sdk/gateway # AI gateway / OpenRouter / proxies -``` - -然后注册服务及一个或多个模型： - -```ts -import { ServiceAI } from '@objectstack/service-ai'; -import { openai } from '@ai-sdk/openai'; -import { anthropic } from '@ai-sdk/anthropic'; - -ServiceAI.configure({ - defaultModel: 'fast', - models: { - fast: openai('gpt-4o-mini'), - smart: openai('gpt-4o'), - claude: anthropic('claude-3-5-sonnet-latest'), - }, - enableStreaming: true, - maxHistoryLength: 50, -}); -``` - -Provider API key 来自各 SDK 的标准环境变量： - -| Provider | 环境变量 | -|---|---| -| OpenAI | `OPENAI_API_KEY` | -| Anthropic | `ANTHROPIC_API_KEY` | -| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | -| AI Gateway | `AI_GATEWAY_API_KEY` | - -也可以在 Console 中作为运行时设置粘贴这些值——经过相同的优先级（env > settings），但实时编辑意味着无需重启。 - -### 在代码中使用 AI 服务 - -```ts -const ai = kernel.getService('ai'); - -const convo = await ai.createConversation({ - model: 'smart', - systemPrompt: 'You are a helpful assistant.', -}); - -const reply = await ai.sendMessage({ - conversationId: convo.id, - message: 'Summarize ObjectStack in two sentences.', -}); -``` - -### 在流程中使用 - -`automation` 能力暴露了一个 `ai_call` 步骤类型： - -```ts -{ - type: 'action', - action: 'ai_call', - inputs: { - model: 'fast', - prompt: 'Categorize this ticket: {!trigger.record.subject}', - schema: { category: 'string', priority: 'string' }, - }, - output: 'classified', -} -``` - -详见 [Flows & Automation](/docs/build/automation/flows)。 - -## Embedder - -Embedder 服务把文本转换为稠密向量。ObjectStack 为多个 Provider 提供了适配器——因为 embedding 生态迭代很快，最佳选择取决于成本、延迟和语言。 - -| Provider | 适配器 | 说明 | -|---|---|---| -| OpenAI | `@objectstack/embedder-openai` | `text-embedding-3-small`/`-large` | -| Azure OpenAI | `@objectstack/embedder-openai`（Azure 配置） | 企业级，按区域部署 | -| 阿里通义 DashScope | `@objectstack/embedder-dashscope` | `text-embedding-v3` | -| 智谱 GLM | `@objectstack/embedder-zhipu` | `embedding-2` | -| 硅基流动 SiliconFlow | `@objectstack/embedder-siliconflow` | 开源模型聚合 | -| 火山 Doubao | `@objectstack/embedder-doubao` | 字节跳动 | -| MiniMax | `@objectstack/embedder-minimax` | — | -| Ollama（自托管） | `@objectstack/embedder-ollama` | 适合内网/离线 | -| Custom | `@objectstack/embedder-custom` | 接入你自己的 HTTP 端点 | -| None | _内置_ | 完全禁用 embedding | - -在代码中配置： - -```ts -import { ServiceEmbedder } from '@objectstack/service-embedder'; -import { OpenAIEmbedderPlugin } from '@objectstack/embedder-openai'; - -ServiceEmbedder.configure({ defaultModel: 'small' }); -// 然后注册适配器插件： -new OpenAIEmbedderPlugin({ - model: 'text-embedding-3-small', - // OPENAI_API_KEY from env -}); -``` - -或在运行时通过 **Console → Configuration → AI → Embedder** 选择。无需重启切换 Provider；已有向量仍可检索（你可以在后台重建索引）。 - -## Knowledge / RAG - -Knowledge 服务负责文档接入、切块、embedding（通过 Embedder 服务）和检索。底层存储和检索后端可插拔： - -| 适配器 | 后端 | 适用场景 | -|---|---|---| -| `@objectstack/knowledge-memory` | 进程内 | 开发、演示、小型知识库 | -| `@objectstack/knowledge-turso` | Turso/libSQL + sqlite-vss | 单区域生产环境，嵌入式向量 | -| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | 高质量开源 RAG，含切块和重排 | - -```ts -import { ServiceKnowledge } from '@objectstack/service-knowledge'; -import { TursoKnowledgePlugin } from '@objectstack/knowledge-turso'; - -ServiceKnowledge.configure(); -new TursoKnowledgePlugin({ - databaseUrl: process.env.TURSO_DATABASE_URL, - authToken: process.env.TURSO_AUTH_TOKEN, -}); -``` - -已索引的知识库成为一等对象——可以在流程中查询，可以在 Console 中呈现，也可以作为检索上下文挂接到 AI 助手。 - -## MCP —— Model Context Protocol - -ObjectOS 可以通过开放的 [Model Context Protocol](https://modelcontextprotocol.io) 把自己作为工具服务器暴露给 AI Agent（Claude Desktop、IDE、自定义 Agent）。 - -```ts -import { McpServerPlugin } from '@objectstack/mcp'; - -new McpServerPlugin({ - // expose specific objects + actions as MCP tools - expose: ['todo_task', 'support_ticket'], -}); -``` - -Agent 通过 MCP 发现并调用 ObjectOS 的 Action——遵循调用用户的权限集。MCP 服务器还暴露一小组通用工具：`search_records`、`get_record`、`create_record`、`invoke_action`。 - -## 运行保证 - -- **无强制云依赖。** 使用 Ollama 做对话 + Ollama Embedder + memory knowledge —— 完全离线可用。 -- **可热切换。** 在 Console 修改 Provider；新请求在下次调用时使用新 Provider，无需重启。 -- **按租户配置。** 每个 Environment 拥有独立的 AI 设置。租户 A 用 OpenAI，租户 B 用 Anthropic —— 同一运行时。 -- **审计日志条目。** 每次会话、工具调用、Embedder 请求都可被审计（`@objectstack/plugin-audit`）。 -- **成本可感知。** Token 数和 Provider ID 写入审计日志，便于成本分摊/分析。 - -## 下一步 - -- [Flows & Automation](/docs/build/automation/flows) —— 在声明式业务逻辑中调用 AI -- [Marketplace](/docs/build/marketplace) —— 默认应用市场中的 AI 应用 -- [Security & Compliance](/docs/reference/security) —— AI 数据流是如何隔离的 -- [`@objectstack/service-ai` 源码](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-ai) -- [`@objectstack/service-embedder` 源码](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-embedder) -- [`@objectstack/service-knowledge` 源码](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-knowledge) diff --git a/content/docs/configure/ai.zh-Hant.mdx b/content/docs/configure/ai.zh-Hant.mdx deleted file mode 100644 index 7ce9eef..0000000 --- a/content/docs/configure/ai.zh-Hant.mdx +++ /dev/null @@ -1,183 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: AI 服務 -description: LLM、Embedder、RAG 與 MCP —— 多 Provider 可插拔，執行時可切換。 -translation: - source_sha: 1b89f2c7f43c0a3ac7a72c4fe461f58764838f7d48072dda6395534452731230 - guide_rev: 1 - mode: auto ---- - -ObjectOS 把 AI 視為一等能力，分為**三個可插拔層**： - -| 層 | 包 | 作用 | -|---|---|---| -| **Chat / 生成** | `@objectstack/service-ai` | 會話、工具呼叫、流式輸出 | -| **Embeddings** | `@objectstack/service-embedder` + 介面卡 | 文本 → 向量，用於語義搜尋和 RAG | -| **Knowledge / RAG** | `@objectstack/service-knowledge` + 介面卡 | 文件 → 已索引的知識庫 | - -三層都是可選的，都是與 Provider 解耦的，並且都可以在 **Console → Configuration** 中執行時重配，無需重啟。 - -## Chat / 生成 - -由 [Vercel AI SDK](https://ai-sdk.dev) 驅動。把你想用的 Provider 作為 peer 依賴安裝： - -```bash -pnpm add @ai-sdk/openai # OpenAI -pnpm add @ai-sdk/anthropic # Claude -pnpm add @ai-sdk/google # Gemini -pnpm add @ai-sdk/gateway # AI gateway / OpenRouter / proxies -``` - -然後註冊服務及一個或多個模型： - -```ts -import { ServiceAI } from '@objectstack/service-ai'; -import { openai } from '@ai-sdk/openai'; -import { anthropic } from '@ai-sdk/anthropic'; - -ServiceAI.configure({ - defaultModel: 'fast', - models: { - fast: openai('gpt-4o-mini'), - smart: openai('gpt-4o'), - claude: anthropic('claude-3-5-sonnet-latest'), - }, - enableStreaming: true, - maxHistoryLength: 50, -}); -``` - -Provider API key 來自各 SDK 的標準環境變數： - -| Provider | 環境變數 | -|---|---| -| OpenAI | `OPENAI_API_KEY` | -| Anthropic | `ANTHROPIC_API_KEY` | -| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | -| AI Gateway | `AI_GATEWAY_API_KEY` | - -也可以在 Console 中作為執行時設定貼上這些值——經過相同的優先順序（env > settings），但即時編輯意味著無需重啟。 - -### 在程式碼中使用 AI 服務 - -```ts -const ai = kernel.getService('ai'); - -const convo = await ai.createConversation({ - model: 'smart', - systemPrompt: 'You are a helpful assistant.', -}); - -const reply = await ai.sendMessage({ - conversationId: convo.id, - message: 'Summarize ObjectStack in two sentences.', -}); -``` - -### 在流程中使用 - -`automation` 能力暴露了一個 `ai_call` 步驟型別： - -```ts -{ - type: 'action', - action: 'ai_call', - inputs: { - model: 'fast', - prompt: 'Categorize this ticket: {!trigger.record.subject}', - schema: { category: 'string', priority: 'string' }, - }, - output: 'classified', -} -``` - -詳見 [Flows & Automation](/docs/build/automation/flows)。 - -## Embedder - -Embedder 服務把文本轉換為稠密向量。ObjectStack 為多個 Provider 提供了介面卡——因為 embedding 生態迭代很快，最佳選擇取決於成本、延遲和語言。 - -| Provider | 介面卡 | 說明 | -|---|---|---| -| OpenAI | `@objectstack/embedder-openai` | `text-embedding-3-small`/`-large` | -| Azure OpenAI | `@objectstack/embedder-openai`（Azure 配置） | 企業級，按區域部署 | -| 阿里通義 DashScope | `@objectstack/embedder-dashscope` | `text-embedding-v3` | -| 智譜 GLM | `@objectstack/embedder-zhipu` | `embedding-2` | -| 矽基流動 SiliconFlow | `@objectstack/embedder-siliconflow` | 開源模型聚合 | -| 火山 Doubao | `@objectstack/embedder-doubao` | 字節跳動 | -| MiniMax | `@objectstack/embedder-minimax` | — | -| Ollama（自託管） | `@objectstack/embedder-ollama` | 適合內網/離線 | -| Custom | `@objectstack/embedder-custom` | 接入你自己的 HTTP 端點 | -| None | _內建_ | 完全停用 embedding | - -在程式碼中配置： - -```ts -import { ServiceEmbedder } from '@objectstack/service-embedder'; -import { OpenAIEmbedderPlugin } from '@objectstack/embedder-openai'; - -ServiceEmbedder.configure({ defaultModel: 'small' }); -// 然后注册适配器插件： -new OpenAIEmbedderPlugin({ - model: 'text-embedding-3-small', - // OPENAI_API_KEY from env -}); -``` - -或在執行時通過 **Console → Configuration → AI → Embedder** 選擇。無需重啟切換 Provider；已有向量仍可檢索（你可以在後臺重建索引）。 - -## Knowledge / RAG - -Knowledge 服務負責文件接入、切塊、embedding（通過 Embedder 服務）和檢索。底層儲存和檢索後端可插拔： - -| 介面卡 | 後端 | 適用場景 | -|---|---|---| -| `@objectstack/knowledge-memory` | 程序內 | 開發、演示、小型知識庫 | -| `@objectstack/knowledge-turso` | Turso/libSQL + sqlite-vss | 單區域生產環境，嵌入式向量 | -| `@objectstack/knowledge-ragflow` | [RAGFlow](https://github.com/infiniflow/ragflow) | 高質量開源 RAG，含切塊和重排 | - -```ts -import { ServiceKnowledge } from '@objectstack/service-knowledge'; -import { TursoKnowledgePlugin } from '@objectstack/knowledge-turso'; - -ServiceKnowledge.configure(); -new TursoKnowledgePlugin({ - databaseUrl: process.env.TURSO_DATABASE_URL, - authToken: process.env.TURSO_AUTH_TOKEN, -}); -``` - -已索引的知識庫成為一等物件——可以在流程中查詢，可以在 Console 中呈現，也可以作為檢索上下文掛接到 AI 助手。 - -## MCP —— Model Context Protocol - -ObjectOS 可以通過開放的 [Model Context Protocol](https://modelcontextprotocol.io) 把自己作為工具伺服器暴露給 AI Agent（Claude Desktop、IDE、自定義 Agent）。 - -```ts -import { McpServerPlugin } from '@objectstack/mcp'; - -new McpServerPlugin({ - // expose specific objects + actions as MCP tools - expose: ['todo_task', 'support_ticket'], -}); -``` - -Agent 通過 MCP 發現並呼叫 ObjectOS 的 Action——遵循呼叫使用者的許可權集。MCP 伺服器還暴露一小組通用工具：`search_records`、`get_record`、`create_record`、`invoke_action`。 - -## 執行保證 - -- **無強制雲依賴。** 使用 Ollama 做對話 + Ollama Embedder + memory knowledge —— 完全離線可用。 -- **可熱切換。** 在 Console 修改 Provider；新請求在下次呼叫時使用新 Provider，無需重啟。 -- **按租戶配置。** 每個 Environment 擁有獨立的 AI 設定。租戶 A 用 OpenAI，租戶 B 用 Anthropic —— 同一執行時。 -- **審計日誌條目。** 每次會話、工具呼叫、Embedder 請求都可被審計（`@objectstack/plugin-audit`）。 -- **成本可感知。** Token 數和 Provider ID 寫入審計日誌，便於成本分攤/分析。 - -## 下一步 - -- [Flows & Automation](/docs/build/automation/flows) —— 在宣告式業務邏輯中呼叫 AI -- [Marketplace](/docs/build/marketplace) —— 預設應用市場中的 AI 應用 -- [Security & Compliance](/docs/reference/security) —— AI 資料流是如何隔離的 -- [`@objectstack/service-ai` 原始碼](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-ai) -- [`@objectstack/service-embedder` 原始碼](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-embedder) -- [`@objectstack/service-knowledge` 原始碼](https://github.com/objectstack-ai/objectstack/tree/main/packages/services/service-knowledge) diff --git a/content/docs/operate/upgrade.de.mdx b/content/docs/operate/upgrade.de.mdx deleted file mode 100644 index 4beb3d0..0000000 --- a/content/docs/operate/upgrade.de.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Upgrade und Rollback -description: ObjectOS und Anwendungsartefakte sicher aktualisieren. -translation: - source_sha: 89f99be032a0a531905c47128ae2aa8bfd5ef74b1d371c6adb09096c9ca9825a - guide_rev: 1 - mode: auto ---- - -ObjectOS hat zwei Versionsstränge: - -| Version | Verantwortlich | Rollback | -|---|---|---| -| ObjectOS-Image/Runtime | Plattform-/Runtime-Team | Vorheriger Container-Tag | -| Anwendungsartefakt | Anwendungs-/Control-Plane-Release | Vorheriges Artefakt oder Projektversions-Zeiger | - -Ändern Sie Artefakte nicht direkt. Veröffentlichen Sie ein neues Artefakt und -schalten Sie die Runtime darauf um. - -## ObjectOS aktualisieren - -Für Docker Compose: - -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml up -d -``` - -Aktualisieren Sie für Kubernetes den Image-Tag und lassen Sie das Deployment rollen. - -## Artefakt aktualisieren - -Dateibasierter Modus: - -```bash -cp objectstack-2026-05-24.json docker/artifacts/objectstack.json -docker compose -f docker/docker-compose.yml restart objectos -``` - -Cloud-verbundener Modus: - -1. Veröffentlichen Sie das neue Artefakt in der Control Plane. -2. Verschieben Sie den aktuellen Projekt-/Umgebungszeiger auf die neue Version. -3. Lassen Sie ObjectOS nach Ablauf des Caches neu abrufen oder starten Sie neu, um ein Neuladen zu erzwingen. - -## Rollback - -ObjectOS zurückrollen: Pinnen Sie den vorherigen Image-Tag in Ihrer Compose-Datei -(oder im Deployment-Manifest) und wenden Sie ihn erneut an. - -```bash -docker compose -f docker/docker-compose.yml up -d objectos -``` - -Artefakt zurückrollen: - -- Stellen Sie die vorherige gemountete Datei wieder her; oder -- Verschieben Sie den Control-Plane-Zeiger zurück auf die vorherige Artefaktversion. - -## Kompatibilitätsprüfungen - -Vor dem Upgrade: - -- bestätigen Sie, dass das Artefakt gegen eine kompatible ObjectStack-Version erstellt wurde; -- bestätigen Sie, dass die erforderlichen Funktionen im ObjectOS-Image verfügbar sind; -- bestätigen Sie, dass das Verhalten von Datenbankmigrationen oder Schema-Sync verstanden wurde; -- führen Sie Smoke-Tests für Authentifizierung und Berechtigungen durch; -- stellen Sie sicher, dass das Rollback keine destruktiven Datenänderungen erfordert. diff --git a/content/docs/operate/upgrade.es.mdx b/content/docs/operate/upgrade.es.mdx deleted file mode 100644 index b1ba373..0000000 --- a/content/docs/operate/upgrade.es.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Actualización y reversión -description: Actualiza ObjectOS y los artefactos de la aplicación de forma segura. -translation: - source_sha: 89f99be032a0a531905c47128ae2aa8bfd5ef74b1d371c6adb09096c9ca9825a - guide_rev: 1 - mode: auto ---- - -ObjectOS tiene dos flujos de versiones: - -| Versión | Responsable | Reversión | -|---|---|---| -| Imagen/runtime de ObjectOS | Equipo de plataforma/runtime | Etiqueta del contenedor anterior | -| Artefacto de la aplicación | Publicación de la aplicación/plano de control | Artefacto anterior o puntero de versión del proyecto | - -No modifiques los artefactos en su lugar. Publica un nuevo artefacto y cambia el -runtime para que lo use. - -## Actualizar ObjectOS - -Para Docker Compose: - -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml up -d -``` - -Para Kubernetes, actualiza la etiqueta de la imagen y deja que el despliegue se renueve. - -## Actualizar el artefacto - -Modo basado en archivos: - -```bash -cp objectstack-2026-05-24.json docker/artifacts/objectstack.json -docker compose -f docker/docker-compose.yml restart objectos -``` - -Modo conectado a la nube: - -1. Publica el nuevo artefacto en el plano de control. -2. Mueve el puntero del proyecto/entorno actual a la nueva versión. -3. Deja que ObjectOS vuelva a obtenerlo tras la expiración de la caché o reinícialo para forzar la recarga. - -## Reversión - -Revertir ObjectOS: fija la etiqueta de la imagen anterior en tu archivo Compose (o -manifiesto de despliegue) y vuelve a aplicarlo. - -```bash -docker compose -f docker/docker-compose.yml up -d objectos -``` - -Revertir el artefacto: - -- restaura el archivo montado anterior; o -- mueve el puntero del plano de control de vuelta a la versión anterior del artefacto. - -## Comprobaciones de compatibilidad - -Antes de actualizar: - -- confirma que el artefacto se compiló contra una versión compatible de ObjectStack; -- confirma que las capacidades requeridas están disponibles en la imagen de ObjectOS; -- confirma que se comprende el comportamiento de las migraciones de base de datos o la sincronización del esquema; -- ejecuta pruebas de humo de autenticación y permisos; -- verifica que la reversión no requiere cambios destructivos en los datos. diff --git a/content/docs/operate/upgrade.fr.mdx b/content/docs/operate/upgrade.fr.mdx deleted file mode 100644 index a9ac777..0000000 --- a/content/docs/operate/upgrade.fr.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Mise à niveau et restauration -description: Mettez à niveau ObjectOS et les artefacts d'application en toute sécurité. -translation: - source_sha: 89f99be032a0a531905c47128ae2aa8bfd5ef74b1d371c6adb09096c9ca9825a - guide_rev: 1 - mode: auto ---- - -ObjectOS possède deux flux de versions : - -| Version | Responsable | Restauration | -|---|---|---| -| Image/runtime ObjectOS | Équipe plateforme/runtime | Tag de conteneur précédent | -| Artefact d'application | Publication application/plan de contrôle | Artefact précédent ou pointeur de version du projet | - -Ne modifiez pas les artefacts en place. Publiez un nouvel artefact et faites pointer le -runtime vers celui-ci. - -## Mettre à niveau ObjectOS - -Pour Docker Compose : - -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml up -d -``` - -Pour Kubernetes, mettez à jour le tag de l'image et laissez le déploiement se dérouler. - -## Mettre à niveau l'artefact - -Mode basé sur fichier : - -```bash -cp objectstack-2026-05-24.json docker/artifacts/objectstack.json -docker compose -f docker/docker-compose.yml restart objectos -``` - -Mode connecté au cloud : - -1. Publiez le nouvel artefact sur le plan de contrôle. -2. Déplacez le pointeur de projet/environnement actuel vers la nouvelle version. -3. Laissez ObjectOS récupérer à nouveau les données après l'expiration du cache ou redémarrez pour forcer le rechargement. - -## Restauration - -Restaurer ObjectOS : épinglez le tag d'image précédent dans votre fichier Compose (ou -votre manifeste de déploiement), puis réappliquez-le. - -```bash -docker compose -f docker/docker-compose.yml up -d objectos -``` - -Restaurer l'artefact : - -- restaurez le fichier monté précédent ; ou -- ramenez le pointeur du plan de contrôle vers la version d'artefact précédente. - -## Vérifications de compatibilité - -Avant la mise à niveau : - -- confirmez que l'artefact a été construit pour une version compatible d'ObjectStack ; -- confirmez que les capacités requises sont disponibles dans l'image ObjectOS ; -- confirmez que les migrations de base de données ou le comportement de synchronisation du schéma sont bien compris ; -- exécutez des tests de fumée d'authentification et de permissions ; -- vérifiez que la restauration ne nécessite pas de modifications destructrices des données. diff --git a/content/docs/operate/upgrade.ja.mdx b/content/docs/operate/upgrade.ja.mdx deleted file mode 100644 index 28dad4e..0000000 --- a/content/docs/operate/upgrade.ja.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: アップグレードとロールバック -description: ObjectOS とアプリケーションアーティファクトを安全にアップグレードします。 -translation: - source_sha: 89f99be032a0a531905c47128ae2aa8bfd5ef74b1d371c6adb09096c9ca9825a - guide_rev: 1 - mode: auto ---- - -ObjectOS には 2 つのバージョンストリームがあります。 - -| バージョン | 所有者 | ロールバック | -|---|---|---| -| ObjectOS イメージ/ランタイム | プラットフォーム/ランタイムチーム | 以前のコンテナタグ | -| アプリケーションアーティファクト | アプリケーション/コントロールプレーンのリリース | 以前のアーティファクトまたはプロジェクトバージョンポインター | - -アーティファクトをその場で変更しないでください。新しいアーティファクトを公開し、 -ランタイムをそれに切り替えてください。 - -## ObjectOS のアップグレード - -Docker Compose の場合: - -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml up -d -``` - -Kubernetes の場合は、イメージタグを更新し、デプロイメントをロールさせます。 - -## アーティファクトのアップグレード - -ファイルベースモード: - -```bash -cp objectstack-2026-05-24.json docker/artifacts/objectstack.json -docker compose -f docker/docker-compose.yml restart objectos -``` - -クラウド接続モード: - -1. 新しいアーティファクトをコントロールプレーンに公開します。 -2. 現在のプロジェクト/環境ポインターを新しいバージョンに移動します。 -3. キャッシュの有効期限切れ後に ObjectOS を再取得させるか、再起動して強制的に再読み込みします。 - -## ロールバック - -ObjectOS のロールバック: Compose ファイル（またはデプロイメントマニフェスト）で -以前のイメージタグを固定し、それを再適用します。 - -```bash -docker compose -f docker/docker-compose.yml up -d objectos -``` - -アーティファクトのロールバック: - -- 以前のマウントされたファイルを復元する。または -- コントロールプレーンのポインターを以前のアーティファクトバージョンに戻す。 - -## 互換性チェック - -アップグレードの前に: - -- アーティファクトが互換性のある ObjectStack バージョンに対してビルドされていることを確認する。 -- 必要な機能が ObjectOS イメージで利用可能であることを確認する。 -- データベースマイグレーションまたはスキーマ同期の動作を理解していることを確認する。 -- 認証および権限のスモークテストを実行する。 -- ロールバックが破壊的なデータ変更を必要としないことを確認する。 diff --git a/content/docs/operate/upgrade.ko.mdx b/content/docs/operate/upgrade.ko.mdx deleted file mode 100644 index 022ad9f..0000000 --- a/content/docs/operate/upgrade.ko.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: 업그레이드 및 롤백 -description: ObjectOS와 애플리케이션 아티팩트를 안전하게 업그레이드하세요. -translation: - source_sha: 89f99be032a0a531905c47128ae2aa8bfd5ef74b1d371c6adb09096c9ca9825a - guide_rev: 1 - mode: auto ---- - -ObjectOS에는 두 가지 버전 스트림이 있습니다. - -| 버전 | 소유자 | 롤백 | -|---|---|---| -| ObjectOS 이미지/런타임 | 플랫폼/런타임 팀 | 이전 컨테이너 태그 | -| 애플리케이션 아티팩트 | 애플리케이션/컨트롤 플레인 릴리스 | 이전 아티팩트 또는 프로젝트 버전 포인터 | - -아티팩트를 제자리에서 변경하지 마세요. 새 아티팩트를 게시하고 런타임을 해당 -아티팩트로 전환하세요. - -## ObjectOS 업그레이드 - -Docker Compose의 경우: - -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml up -d -``` - -Kubernetes의 경우, 이미지 태그를 업데이트하고 배포가 롤링되도록 하세요. - -## 아티팩트 업그레이드 - -파일 기반 모드: - -```bash -cp objectstack-2026-05-24.json docker/artifacts/objectstack.json -docker compose -f docker/docker-compose.yml restart objectos -``` - -클라우드 연결 모드: - -1. 새 아티팩트를 컨트롤 플레인에 게시합니다. -2. 현재 프로젝트/환경 포인터를 새 버전으로 이동합니다. -3. 캐시 만료 후 ObjectOS가 다시 가져오도록 하거나 재시작하여 강제로 다시 로드합니다. - -## 롤백 - -ObjectOS 롤백: Compose 파일(또는 배포 매니페스트)에서 이전 이미지 태그를 고정한 -다음 다시 적용하세요. - -```bash -docker compose -f docker/docker-compose.yml up -d objectos -``` - -아티팩트 롤백: - -- 이전에 마운트된 파일을 복원하거나, -- 컨트롤 플레인 포인터를 이전 아티팩트 버전으로 되돌립니다. - -## 호환성 점검 - -업그레이드 전에: - -- 아티팩트가 호환되는 ObjectStack 버전으로 빌드되었는지 확인합니다. -- 필요한 기능이 ObjectOS 이미지에서 사용 가능한지 확인합니다. -- 데이터베이스 마이그레이션 또는 스키마 동기화 동작을 이해하고 있는지 확인합니다. -- 인증 및 권한 스모크 테스트를 실행합니다. -- 롤백이 파괴적인 데이터 변경을 요구하지 않는지 확인합니다. diff --git a/content/docs/operate/upgrade.mdx b/content/docs/operate/upgrade.mdx index a88672c..28ede08 100644 --- a/content/docs/operate/upgrade.mdx +++ b/content/docs/operate/upgrade.mdx @@ -1,64 +1,51 @@ --- title: Upgrade and Rollback -description: Upgrade ObjectOS and application artifacts safely. +description: Upgrade or roll back ObjectOS Self-Managed by changing the image digest it pins, after backing up the database. --- -ObjectOS has two version streams: - -| Version | Owner | Rollback | -|---|---|---| -| ObjectOS image/runtime | Platform/runtime team | Previous container tag | -| Application artifact | Application/control-plane release | Previous artifact or project version pointer | - -Do not mutate artifacts in place. Publish a new artifact and switch the -runtime to it. - -## Upgrade ObjectOS - -For Docker Compose: - -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml up -d -``` - -For Kubernetes, update the image tag and let the deployment roll. - -## Upgrade artifact - -File-backed mode: - -```bash -cp objectstack-2026-05-24.json docker/artifacts/objectstack.json -docker compose -f docker/docker-compose.yml restart objectos -``` - -Cloud-connected mode: - -1. Publish the new artifact to the control plane. -2. Move the current project/environment pointer to the new version. -3. Let ObjectOS refetch after cache expiry or restart to force reload. - -## Rollback - -Rollback ObjectOS: pin the previous image tag in your Compose file (or -deployment manifest), then re-apply it. - -```bash -docker compose -f docker/docker-compose.yml up -d objectos -``` - -Rollback artifact: - -- restore the previous mounted file; or -- move the control-plane pointer back to the previous artifact version. - -## Compatibility checks - -Before upgrading: - -- confirm the artifact was built against a compatible ObjectStack version; -- confirm required capabilities are available in the ObjectOS image; -- confirm database migrations or schema sync behavior are understood; -- run authentication and permission smoke tests; -- verify rollback does not require destructive data changes. +On ObjectOS Self-Managed, the image you run is pinned by **digest**, never by +a tag, so an upgrade is a change of digest and a rollback is the previous +one. [Docker → Upgrade and rollback](/docs/deploy/docker#upgrade-and-rollback) +documents this procedure and the reason for each step; this page repeats it as +a checklist. + +## Upgrade + +1. Take the **new digest** from the release notes and read the image's + [release manifest](/docs/deploy/docker#the-image-can-tell-you-what-it-is) + before rolling it out: confirm the product major line is the one you are + on, and check whether the embedded runtime's compatibility range moved. A + runtime major-version move means breaking changes underneath — read that + release's notes first. +2. **Back up the database.** Schema migrations are *forward*: rolling the + image back does not roll the schema back. +3. Change the image digest and restart the stack. The migration runs to + completion before new replicas take traffic. +4. Confirm readiness (`/api/v1/ready`) returns 200 and the replicas report + healthy. + +## Roll back + +Keep the **previous** digest: that is what a rollback is. To roll back, +restore the previous digest and repeat step 3 — valid as long as the version +you are leaving made no incompatible schema change (the release notes say +when it did). + +## On Kubernetes and air-gapped sites + +- **Kubernetes** — upgrading is the same change of image digest, with the + migration Job running to completion before the new replicas serve. See + [Kubernetes → Rolling upgrades change the digest](/docs/deploy/kubernetes#rolling-upgrades-change-the-digest). +- **Air-gapped** — verify the new digest outside, transfer it in, change the + pinned digest, restart. Keep the previous digest: inside an air-gapped + network it may be the only copy you have to roll back to. See + [Air-gapped → Getting the image inside the network](/docs/deploy/air-gapped#getting-the-image-inside-the-network). + +## The app versions separately + +The app itself, when it is delivered as a published artifact, versions +independently of the image — see +[Deployment → How the app gets in](/docs/deploy#how-the-app-gets-in). Treat +published artifacts as immutable: if you overwrite one in place, you lose the +ability to roll back cleanly even when the database backup is perfect +([Backup → Artifact versioning](/docs/operate/backup#artifact-versioning)). diff --git a/content/docs/operate/upgrade.zh-Hans.mdx b/content/docs/operate/upgrade.zh-Hans.mdx deleted file mode 100644 index 44d0b00..0000000 --- a/content/docs/operate/upgrade.zh-Hans.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: 升级与回滚 -description: 安全地升级 ObjectOS 与应用制品。 -translation: - source_sha: 89f99be032a0a531905c47128ae2aa8bfd5ef74b1d371c6adb09096c9ca9825a - guide_rev: 1 - mode: auto ---- - -ObjectOS 有两条版本流： - -| 版本 | 所有者 | 回滚 | -|---|---|---| -| ObjectOS 镜像/运行时 | 平台/运行时团队 | 上一个容器标签 | -| 应用制品 | 应用/控制平面发布 | 上一个制品或项目版本指针 | - -不要就地修改制品。请发布一个新制品，并将运行时切换到它。 - -## 升级 ObjectOS - -对于 Docker Compose： - -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml up -d -``` - -对于 Kubernetes，更新镜像标签并让部署自动滚动更新。 - -## 升级制品 - -文件支撑模式： - -```bash -cp objectstack-2026-05-24.json docker/artifacts/objectstack.json -docker compose -f docker/docker-compose.yml restart objectos -``` - -云连接模式： - -1. 将新制品发布到控制平面。 -2. 将当前项目/环境指针指向新版本。 -3. 让 ObjectOS 在缓存过期后重新拉取，或重启以强制重新加载。 - -## 回滚 - -回滚 ObjectOS：在你的 Compose 文件（或部署清单）中固定上一个镜像标签，然后重新应用它。 - -```bash -docker compose -f docker/docker-compose.yml up -d objectos -``` - -回滚制品： - -- 恢复之前挂载的文件；或 -- 将控制平面指针移回上一个制品版本。 - -## 兼容性检查 - -升级前： - -- 确认制品是针对兼容的 ObjectStack 版本构建的； -- 确认所需能力在 ObjectOS 镜像中可用； -- 确认理解数据库迁移或模式同步行为； -- 运行身份验证与权限冒烟测试； -- 验证回滚不需要进行破坏性的数据变更。 diff --git a/content/docs/operate/upgrade.zh-Hant.mdx b/content/docs/operate/upgrade.zh-Hant.mdx deleted file mode 100644 index 8c2ad16..0000000 --- a/content/docs/operate/upgrade.zh-Hant.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 升級與回滾 -description: 安全地升級 ObjectOS 與應用製品。 -translation: - source_sha: 89f99be032a0a531905c47128ae2aa8bfd5ef74b1d371c6adb09096c9ca9825a - guide_rev: 1 - mode: auto ---- - -ObjectOS 有兩條版本流： - -| 版本 | 所有者 | 回滾 | -|---|---|---| -| ObjectOS 映象/執行時 | 平臺/執行時團隊 | 上一個容器標籤 | -| 應用製品 | 應用/控制平面釋出 | 上一個製品或專案版本指標 | - -不要就地修改製品。請釋出一個新制品，並將執行時切換到它。 - -## 升級 ObjectOS - -對於 Docker Compose： - -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml up -d -``` - -對於 Kubernetes，更新映象標籤並讓部署自動滾動更新。 - -## 升級製品 - -檔案支撐模式： - -```bash -cp objectstack-2026-05-24.json docker/artifacts/objectstack.json -docker compose -f docker/docker-compose.yml restart objectos -``` - -雲連線模式： - -1. 將新制品釋出到控制平面。 -2. 將當前專案/環境指標指向新版本。 -3. 讓 ObjectOS 在快取過期後重新拉取，或重啟以強制重新載入。 - -## 回滾 - -回滾 ObjectOS：在你的 Compose 檔案（或部署清單）中固定上一個映象標籤，然後重新應用它。 - -```bash -docker compose -f docker/docker-compose.yml up -d objectos -``` - -回滾製品： - -- 恢復之前掛載的檔案；或 -- 將控制平面指標移回上一個製品版本。 - -## 相容性檢查 - -升級前： - -- 確認製品是針對相容的 ObjectStack 版本構建的； -- 確認所需能力在 ObjectOS 映象中可用； -- 確認理解資料庫遷移或模式同步行為； -- 執行身份驗證與許可權冒煙測試； -- 驗證回滾不需要進行破壞性的資料變更。 diff --git a/content/docs/reference/runtime-capabilities.de.mdx b/content/docs/reference/runtime-capabilities.de.mdx deleted file mode 100644 index 7b117bb..0000000 --- a/content/docs/reference/runtime-capabilities.de.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Laufzeit-Funktionen -description: Funktionen, die ObjectOS aus ObjectStack-Framework-Paketen laden kann. -translation: - source_sha: 75639417a7e7a0851ea5a5fbbd3b6595aa6ba61004d1014e15954d430a9b909f - guide_rev: 1 - mode: auto ---- - -ObjectOS lädt für jedes Projekt eine Basis-Laufzeitumgebung und installiert -anschließend die optionalen Funktionen, die vom Anwendungsartefakt deklariert -werden. - -## Basis-Laufzeitumgebung - -Der Basis-Projektkernel umfasst: - -- ObjectKernel-Lebenszyklus und Service-Registry; -- ObjectQL-Datenengine; -- konfigurierter Datentreiber; -- Metadatendienst; -- Registrierung des Anwendungsartefakts; -- Authentifizierung, wenn `OS_AUTH_SECRET` konfiguriert ist; -- Security-Plugin für RBAC, zeilenbasierte Sicherheit und Feldsicherheit; -- i18n-Dienst. - -## Optionale Funktionen - -Artefakte können Funktionen in ihrer `requires`-Liste deklarieren. ObjectOS -lädt passende Framework-Pakete, sofern sie im Image vorhanden sind. - -| Funktion | Paket | Zweck | -|---|---|---| -| `automation` | `@objectstack/service-automation` | Flow-/DAG-Ausführung und Automatisierungsknoten | -| `ai` | `@objectstack/service-ai` | LLM-Adapter, Konversationen, Tools, SSE-Routen | -| `analytics` | `@objectstack/service-analytics` | Cubes, Analyseabfragen, Reporting-Daten | -| `audit` | `@objectstack/plugin-audit` | Audit-Log-Objekt und Audit-Trail | -| `cache` | `@objectstack/service-cache` | Cache-Abstraktion und Adapter | -| `storage` | `@objectstack/service-storage` | Datei-/Objektspeicherdienst | -| `queue` | `@objectstack/service-queue` | Queue-Abstraktion und Worker | -| `job` | `@objectstack/service-job` | Geplante/Hintergrund-Jobs | -| `realtime` | `@objectstack/service-realtime` | WebSocket- und Pub/Sub-Echtzeit | -| `feed` | `@objectstack/service-feed` | Kommentare, Reaktionen, Abonnements, Aktivitäts-Feed | -| `settings` | `@objectstack/service-settings` | Settings-Manifeste und K/V-Resolver | - -Wird eine Funktion angefordert, das Image enthält das Paket jedoch nicht, -**protokolliert ObjectOS eine Warnung und läuft mit deaktivierter Funktion -weiter.** Das ist beabsichtigt – es hält die Laufzeitumgebung auch dann -startfähig, wenn während der Entwicklung ein optionales Paket fehlt – aber in -der **Produktion ist es ein echtes Risiko**: - -- Eine Anwendung, die Audit erfordert und in ein Image ohne - `@objectstack/plugin-audit` geladen wird, startet sauber **und schreibt - kein Audit-Log**. Compliance-Nachweise fehlen, ohne dass ein Fehler - auftritt. -- Eine Job-gesteuerte Anwendung, die in ein Image ohne - `@objectstack/service-job` geladen wird, startet sauber **und führt - geplante Arbeiten stillschweigend nie aus**. - -**Produktions-Checkliste:** - -1. Behandeln Sie Funktionswarnungen als Bereitstellungsfehler. Durchsuchen - Sie die Startprotokolle nach `capability not loaded` (oder Ihrem - Äquivalent) und lassen Sie die Readiness-Probe / das Rollout fehlschlagen, - falls solche Warnungen auftreten. -2. Fixieren Sie das Laufzeit-Image auf eines, das jedes Paket enthält, das - Ihre Artefakte in `requires` deklarieren. -3. Dokumentieren Sie beim Veröffentlichen eines Artefakts dessen - `requires`-Liste mit, damit Betreiber das passende Image überprüfen können. - -## API-Oberfläche - -ObjectOS stellt üblicherweise bereit: - -- generierte REST-APIs; -- Auth-Endpunkte unter `/api/v1/auth/*`; -- Metadaten- und i18n-Endpunkte; -- Dienst-Endpunkte für aktivierte Funktionen. - -GraphQL und OData sind Funktionen auf Framework-Ebene und sollten nur dann als -unterstützt dokumentiert werden, wenn sie vom bereitgestellten -Laufzeitpaket enthalten und aktiviert sind. diff --git a/content/docs/reference/runtime-capabilities.es.mdx b/content/docs/reference/runtime-capabilities.es.mdx deleted file mode 100644 index e6f2af3..0000000 --- a/content/docs/reference/runtime-capabilities.es.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Capacidades de runtime -description: Capacidades que ObjectOS puede cargar desde los paquetes del framework ObjectStack. -translation: - source_sha: 75639417a7e7a0851ea5a5fbbd3b6595aa6ba61004d1014e15954d430a9b909f - guide_rev: 1 - mode: auto ---- - -ObjectOS carga un runtime base para cada proyecto y luego instala las -capacidades opcionales declaradas por el artefacto de la aplicación. - -## Runtime base - -El núcleo base del proyecto incluye: - -- el ciclo de vida de ObjectKernel y el registro de servicios; -- el motor de datos ObjectQL; -- el controlador de datos configurado; -- el servicio de metadatos; -- el registro del artefacto de la aplicación; -- autenticación cuando `OS_AUTH_SECRET` está configurado; -- el plugin de seguridad para RBAC, seguridad a nivel de fila y seguridad de campos; -- el servicio de i18n. - -## Capacidades opcionales - -Los artefactos pueden declarar capacidades en su lista `requires`. ObjectOS -carga los paquetes del framework correspondientes cuando están presentes en la imagen. - -| Capacidad | Paquete | Propósito | -|---|---|---| -| `automation` | `@objectstack/service-automation` | Ejecución de flujos/DAG y nodos de automatización | -| `ai` | `@objectstack/service-ai` | Adaptadores de LLM, conversaciones, herramientas, rutas SSE | -| `analytics` | `@objectstack/service-analytics` | Cubos, consultas de analítica, datos de informes | -| `audit` | `@objectstack/plugin-audit` | Objeto de registro de auditoría y pista de auditoría | -| `cache` | `@objectstack/service-cache` | Abstracción de caché y adaptadores | -| `storage` | `@objectstack/service-storage` | Servicio de almacenamiento de archivos/objetos | -| `queue` | `@objectstack/service-queue` | Abstracción de colas y workers | -| `job` | `@objectstack/service-job` | Trabajos programados/en segundo plano | -| `realtime` | `@objectstack/service-realtime` | WebSocket y realtime mediante pub/sub | -| `feed` | `@objectstack/service-feed` | Comentarios, reacciones, suscripciones, feed de actividad | -| `settings` | `@objectstack/service-settings` | Manifiestos de configuración y resolución de K/V | - -Si se solicita una capacidad pero la imagen no incluye el paquete, -**ObjectOS registra una advertencia y continúa ejecutándose con esa capacidad -deshabilitada.** Esto es intencional: mantiene el runtime arrancable incluso -cuando falta un paquete opcional durante el desarrollo, pero en -**producción es un riesgo real**: - -- Una aplicación que requiere auditoría cargada en una imagen sin - `@objectstack/plugin-audit` arrancará correctamente **y no escribirá ningún - registro de auditoría**. Faltará la evidencia de cumplimiento sin ningún error. -- Una aplicación basada en trabajos cargada en una imagen sin - `@objectstack/service-job` arrancará correctamente **y nunca ejecutará en - silencio el trabajo programado**. - -**Lista de comprobación para producción:** - -1. Trata las advertencias de capacidades como fallos de despliegue. Busca con - grep en los logs de arranque `capability not loaded` (o su equivalente) y - haz que la sonda de readiness / el despliegue fallen si aparece alguna. -2. Fija la imagen del runtime a una que incluya todos los paquetes que tus - artefactos declaran en `requires`. -3. Al publicar un artefacto, documenta su lista `requires` junto a él para - que los operadores puedan verificar la imagen correspondiente. - -## Superficie de API - -ObjectOS expone habitualmente: - -- APIs REST generadas; -- endpoints de autenticación bajo `/api/v1/auth/*`; -- endpoints de metadatos e i18n; -- endpoints de servicio para las capacidades habilitadas. - -GraphQL y OData son capacidades a nivel de framework y solo deben -documentarse como compatibles cuando están incluidas y habilitadas por el -paquete de runtime desplegado. diff --git a/content/docs/reference/runtime-capabilities.fr.mdx b/content/docs/reference/runtime-capabilities.fr.mdx deleted file mode 100644 index d042ab0..0000000 --- a/content/docs/reference/runtime-capabilities.fr.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Capacités d'exécution -description: Capacités qu'ObjectOS peut charger depuis les paquets du framework ObjectStack. -translation: - source_sha: 75639417a7e7a0851ea5a5fbbd3b6595aa6ba61004d1014e15954d430a9b909f - guide_rev: 1 - mode: auto ---- - -ObjectOS charge un runtime de base pour chaque projet, puis installe les -capacités optionnelles déclarées par l'artefact de l'application. - -## Runtime de base - -Le noyau de projet de base comprend : - -- le cycle de vie d'ObjectKernel et le registre de services ; -- le moteur de données ObjectQL ; -- le pilote de données configuré ; -- le service de métadonnées ; -- l'enregistrement de l'artefact de l'application ; -- l'authentification lorsque `OS_AUTH_SECRET` est configuré ; -- le plugin de sécurité pour le RBAC, la sécurité au niveau des lignes et la sécurité des champs ; -- le service i18n. - -## Capacités optionnelles - -Les artefacts peuvent déclarer des capacités dans leur liste `requires`. ObjectOS -charge les paquets de framework correspondants lorsqu'ils sont présents dans l'image. - -| Capacité | Paquet | Objectif | -|---|---|---| -| `automation` | `@objectstack/service-automation` | Exécution de flux/DAG et nœuds d'automatisation | -| `ai` | `@objectstack/service-ai` | Adaptateurs LLM, conversations, outils, routes SSE | -| `analytics` | `@objectstack/service-analytics` | Cubes, requêtes analytiques, données de reporting | -| `audit` | `@objectstack/plugin-audit` | Objet de journal d'audit et piste d'audit | -| `cache` | `@objectstack/service-cache` | Abstraction de cache et adaptateurs | -| `storage` | `@objectstack/service-storage` | Service de stockage de fichiers/objets | -| `queue` | `@objectstack/service-queue` | Abstraction de file d'attente et workers | -| `job` | `@objectstack/service-job` | Tâches planifiées/en arrière-plan | -| `realtime` | `@objectstack/service-realtime` | Temps réel WebSocket et pub/sub | -| `feed` | `@objectstack/service-feed` | Commentaires, réactions, abonnements, flux d'activité | -| `settings` | `@objectstack/service-settings` | Manifestes de paramètres et résolveur clé/valeur | - -Si une capacité est demandée mais que l'image n'inclut pas le paquet, -**ObjectOS enregistre un avertissement et continue de fonctionner avec cette -capacité désactivée.** C'est intentionnel — cela permet de maintenir le runtime -démarrable même lorsqu'un paquet optionnel est absent pendant le développement — mais en -**production, c'est un risque réel** : - -- Une application nécessitant l'audit chargée dans une image sans - `@objectstack/plugin-audit` démarrera correctement **et n'écrira aucun - journal d'audit**. Les preuves de conformité seront manquantes sans aucune erreur. -- Une application pilotée par des tâches chargée dans une image sans - `@objectstack/service-job` démarrera correctement **et n'exécutera silencieusement jamais - les travaux planifiés**. - -**Liste de contrôle pour la production :** - -1. Traitez les avertissements de capacité comme des échecs de déploiement. Recherchez dans les journaux de démarrage - `capability not loaded` (ou son équivalent) et faites échouer la - sonde de disponibilité / le déploiement si l'un d'eux apparaît. -2. Épinglez l'image du runtime à une image qui inclut chaque paquet que vos - artefacts déclarent dans `requires`. -3. Lors de la publication d'un artefact, documentez sa liste `requires` à côté de - lui afin que les opérateurs puissent vérifier l'image correspondante. - -## Surface d'API - -ObjectOS expose couramment : - -- des API REST générées ; -- des points de terminaison d'authentification sous `/api/v1/auth/*` ; -- des points de terminaison de métadonnées et d'i18n ; -- des points de terminaison de service pour les capacités activées. - -GraphQL et OData sont des capacités au niveau du framework et ne doivent être -documentés comme pris en charge que lorsqu'ils sont inclus et activés par le paquet -de runtime déployé. diff --git a/content/docs/reference/runtime-capabilities.ja.mdx b/content/docs/reference/runtime-capabilities.ja.mdx deleted file mode 100644 index 763d2b9..0000000 --- a/content/docs/reference/runtime-capabilities.ja.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: ランタイム機能 -description: ObjectOS が ObjectStack フレームワークパッケージから読み込める機能。 -translation: - source_sha: 75639417a7e7a0851ea5a5fbbd3b6595aa6ba61004d1014e15954d430a9b909f - guide_rev: 1 - mode: auto ---- - -ObjectOS はすべてのプロジェクトに対してベースランタイムを読み込み、その後アプリケーションアーティファクトによって宣言されたオプション機能をインストールします。 - -## ベースランタイム - -ベースプロジェクトカーネルには以下が含まれます。 - -- ObjectKernel のライフサイクルとサービスレジストリ -- ObjectQL データエンジン -- 構成されたデータドライバ -- メタデータサービス -- アプリケーションアーティファクトの登録 -- `OS_AUTH_SECRET` が構成されている場合の認証 -- RBAC、行レベルセキュリティ、フィールドセキュリティのためのセキュリティプラグイン -- i18n サービス - -## オプション機能 - -アーティファクトは `requires` リストに機能を宣言できます。ObjectOS はイメージ内に存在する場合、一致するフレームワークパッケージを読み込みます。 - -| 機能 | パッケージ | 目的 | -|---|---|---| -| `automation` | `@objectstack/service-automation` | Flow/DAG の実行と自動化ノード | -| `ai` | `@objectstack/service-ai` | LLM アダプタ、会話、ツール、SSE ルート | -| `analytics` | `@objectstack/service-analytics` | Cube、分析クエリ、レポートデータ | -| `audit` | `@objectstack/plugin-audit` | 監査ログオブジェクトと監査証跡 | -| `cache` | `@objectstack/service-cache` | キャッシュ抽象化とアダプタ | -| `storage` | `@objectstack/service-storage` | ファイル/オブジェクトストレージサービス | -| `queue` | `@objectstack/service-queue` | キュー抽象化とワーカー | -| `job` | `@objectstack/service-job` | スケジュールされた/バックグラウンドのジョブ | -| `realtime` | `@objectstack/service-realtime` | WebSocket と pub/sub のリアルタイム | -| `feed` | `@objectstack/service-feed` | コメント、リアクション、サブスクリプション、アクティビティフィード | -| `settings` | `@objectstack/service-settings` | 設定マニフェストと K/V リゾルバ | - -機能がリクエストされたものの、イメージにそのパッケージが含まれていない場合、**ObjectOS は警告をログに記録し、その機能を無効にしたまま実行を継続します。** これは意図的なものであり、開発中にオプションパッケージが欠落していてもランタイムを起動可能に保つためですが、**本番環境では実際のリスクとなります**。 - -- 監査が必須のアプリを `@objectstack/plugin-audit` を含まないイメージに読み込むと、正常に起動し、**監査ログを一切書き込みません**。コンプライアンスの証跡が、何のエラーもなく欠落することになります。 -- ジョブ駆動のアプリを `@objectstack/service-job` を含まないイメージに読み込むと、正常に起動し、**スケジュールされた作業を黙って一切実行しません**。 - -**本番環境のチェックリスト:** - -1. 機能の警告をデプロイの失敗として扱ってください。起動ログから `capability not loaded`(またはそれに相当するもの)を grep し、いずれかが出現した場合はレディネスプローブ / ロールアウトを失敗させてください。 -2. アーティファクトが `requires` で宣言するすべてのパッケージを含むランタイムイメージにピン留めしてください。 -3. アーティファクトを公開する際には、その `requires` リストを併せてドキュメント化し、運用者が一致するイメージを検証できるようにしてください。 - -## API サーフェス - -ObjectOS は一般的に以下を公開します。 - -- 生成された REST API -- `/api/v1/auth/*` 配下の認証エンドポイント -- メタデータと i18n のエンドポイント -- 有効化された機能のサービスエンドポイント - -GraphQL と OData はフレームワークレベルの機能であり、デプロイされたランタイムパッケージに含まれ、有効化されている場合にのみサポート対象としてドキュメント化されるべきです。 diff --git a/content/docs/reference/runtime-capabilities.ko.mdx b/content/docs/reference/runtime-capabilities.ko.mdx deleted file mode 100644 index 7a6d31b..0000000 --- a/content/docs/reference/runtime-capabilities.ko.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: 런타임 기능 -description: ObjectOS가 ObjectStack 프레임워크 패키지에서 로드할 수 있는 기능. -translation: - source_sha: 75639417a7e7a0851ea5a5fbbd3b6595aa6ba61004d1014e15954d430a9b909f - guide_rev: 1 - mode: auto ---- - -ObjectOS는 모든 프로젝트에 대해 기본 런타임을 로드한 다음, 애플리케이션 -아티팩트가 선언한 선택적 기능을 설치합니다. - -## 기본 런타임 - -기본 프로젝트 커널에는 다음이 포함됩니다. - -- ObjectKernel 라이프사이클 및 서비스 레지스트리; -- ObjectQL 데이터 엔진; -- 구성된 데이터 드라이버; -- 메타데이터 서비스; -- 애플리케이션 아티팩트 등록; -- `OS_AUTH_SECRET`이 구성된 경우 인증; -- RBAC, 행 수준 보안, 필드 보안을 위한 보안 플러그인; -- i18n 서비스. - -## 선택적 기능 - -아티팩트는 `requires` 목록에 기능을 선언할 수 있습니다. ObjectOS는 -이미지에 존재하는 경우 일치하는 프레임워크 패키지를 로드합니다. - -| 기능 | 패키지 | 용도 | -|---|---|---| -| `automation` | `@objectstack/service-automation` | Flow/DAG 실행 및 자동화 노드 | -| `ai` | `@objectstack/service-ai` | LLM 어댑터, 대화, 도구, SSE 라우트 | -| `analytics` | `@objectstack/service-analytics` | 큐브, 분석 쿼리, 리포팅 데이터 | -| `audit` | `@objectstack/plugin-audit` | 감사 로그 객체 및 감사 추적 | -| `cache` | `@objectstack/service-cache` | 캐시 추상화 및 어댑터 | -| `storage` | `@objectstack/service-storage` | 파일/객체 스토리지 서비스 | -| `queue` | `@objectstack/service-queue` | 큐 추상화 및 워커 | -| `job` | `@objectstack/service-job` | 예약된/백그라운드 작업 | -| `realtime` | `@objectstack/service-realtime` | WebSocket 및 pub/sub 실시간 | -| `feed` | `@objectstack/service-feed` | 댓글, 반응, 구독, 활동 피드 | -| `settings` | `@objectstack/service-settings` | 설정 매니페스트 및 K/V 리졸버 | - -기능이 요청되었지만 이미지에 해당 패키지가 포함되어 있지 않은 경우, -**ObjectOS는 경고를 기록하고 해당 기능을 비활성화한 상태로 계속 -실행됩니다.** 이는 의도된 동작으로, 개발 중에 선택적 패키지가 누락된 -경우에도 런타임이 부팅 가능하도록 유지하기 위함입니다. 하지만 -**프로덕션에서는 실질적인 위험입니다**: - -- `@objectstack/plugin-audit` 없이 이미지에 로드된 감사 필수 앱은 - 정상적으로 시작되지만 **감사 로그를 기록하지 않습니다**. 어떤 오류도 - 없이 컴플라이언스 증거가 누락됩니다. -- `@objectstack/service-job` 없이 이미지에 로드된 작업 기반 앱은 - 정상적으로 시작되지만 **예약된 작업을 조용히 실행하지 않습니다**. - -**프로덕션 체크리스트:** - -1. 기능 경고를 배포 실패로 취급하십시오. 시작 로그에서 - `capability not loaded`(또는 이에 상응하는 메시지)를 검색하고, 해당 - 메시지가 나타나면 준비 상태 프로브 / 롤아웃을 실패시키십시오. -2. 아티팩트가 `requires`에 선언한 모든 패키지를 포함하는 런타임 - 이미지에 고정하십시오. -3. 아티팩트를 게시할 때, 운영자가 일치하는 이미지를 확인할 수 있도록 - 해당 `requires` 목록을 함께 문서화하십시오. - -## API 표면 - -ObjectOS는 일반적으로 다음을 노출합니다. - -- 생성된 REST API; -- `/api/v1/auth/*` 아래의 인증 엔드포인트; -- 메타데이터 및 i18n 엔드포인트; -- 활성화된 기능에 대한 서비스 엔드포인트. - -GraphQL과 OData는 프레임워크 수준의 기능이며, 배포된 런타임 패키지에 -포함되어 활성화된 경우에만 지원되는 것으로 문서화해야 합니다. diff --git a/content/docs/reference/runtime-capabilities.mdx b/content/docs/reference/runtime-capabilities.mdx index dc14100..e6d4e8f 100644 --- a/content/docs/reference/runtime-capabilities.mdx +++ b/content/docs/reference/runtime-capabilities.mdx @@ -27,7 +27,7 @@ loads matching framework packages when present in the image. | Capability | Package | Purpose | |---|---|---| | `automation` | `@objectstack/service-automation` | Flow/DAG execution and automation nodes | -| `ai` | `@objectstack/service-ai` | LLM adapters, conversations, tools, SSE routes | +| `ai` | Not a framework package: the AI runtime ships with ObjectOS ([AI Service](/docs/configure/ai)) | LLM adapters, conversations, tools, SSE routes | | `analytics` | `@objectstack/service-analytics` | Cubes, analytics queries, reporting data | | `audit` | `@objectstack/plugin-audit` | Audit log object and audit trail | | `cache` | `@objectstack/service-cache` | Cache abstraction and adapters | @@ -35,7 +35,6 @@ loads matching framework packages when present in the image. | `queue` | `@objectstack/service-queue` | Queue abstraction and workers | | `job` | `@objectstack/service-job` | Scheduled/background jobs | | `realtime` | `@objectstack/service-realtime` | WebSocket and pub/sub realtime | -| `feed` | `@objectstack/service-feed` | Comments, reactions, subscriptions, activity feed | | `settings` | `@objectstack/service-settings` | Settings manifests and K/V resolver | If a capability is requested but the image does not include the package, diff --git a/content/docs/reference/runtime-capabilities.zh-Hans.mdx b/content/docs/reference/runtime-capabilities.zh-Hans.mdx deleted file mode 100644 index dd8215f..0000000 --- a/content/docs/reference/runtime-capabilities.zh-Hans.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 运行时能力 -description: ObjectOS 能从 ObjectStack 框架包加载的能力。 -translation: - source_sha: 75639417a7e7a0851ea5a5fbbd3b6595aa6ba61004d1014e15954d430a9b909f - guide_rev: 1 - mode: auto ---- - -ObjectOS 为每个项目加载一个基础运行时,然后安装应用 artifact 声明的可选能力。 - -## 基础运行时 - -基础项目内核包含： - -- ObjectKernel 生命周期与服务注册; -- ObjectQL 数据引擎; -- 已配置的数据驱动; -- 元数据服务; -- 应用 artifact 注册; -- 当配置了 `OS_AUTH_SECRET` 时启用认证; -- 用于 RBAC、行级安全和字段安全的 security plugin; -- i18n 服务。 - -## 可选能力 - -Artifact 可在其 `requires` 列表中声明能力。当镜像中存在匹配的框架包时,ObjectOS 会加载它们。 - -| 能力 | 包 | 用途 | -|---|---|---| -| `automation` | `@objectstack/service-automation` | 流程/DAG 执行与自动化节点 | -| `ai` | `@objectstack/service-ai` | LLM 适配器、对话、工具、SSE 路由 | -| `analytics` | `@objectstack/service-analytics` | Cube、分析查询、报表数据 | -| `audit` | `@objectstack/plugin-audit` | 审计日志对象与审计轨迹 | -| `cache` | `@objectstack/service-cache` | 缓存抽象与适配器 | -| `storage` | `@objectstack/service-storage` | 文件/对象存储服务 | -| `queue` | `@objectstack/service-queue` | 队列抽象与 worker | -| `job` | `@objectstack/service-job` | 调度/后台作业 | -| `realtime` | `@objectstack/service-realtime` | WebSocket 与 pub/sub 实时 | -| `feed` | `@objectstack/service-feed` | 评论、反应、订阅、动态信息流 | -| `settings` | `@objectstack/service-settings` | Settings manifest 与 K/V 解析器 | - -如果请求了某能力但镜像未包含该包,**ObjectOS 会记录警告并继续运行,该能力被禁用**。这是有意为之 —— 它使运行时在开发期间即使缺少某个可选包也能启动 —— 但在**生产中这是真实风险**： - -- 加载到不含 `@objectstack/plugin-audit` 镜像的、要求审计的应用,会干净地启动**而不写任何审计日志**。合规证据会在无任何错误的情况下缺失。 -- 加载到不含 `@objectstack/service-job` 镜像的、依赖作业的应用,会干净地启动**而静默地从不运行调度工作**。 - -**生产清单：** - -1. 将能力警告视为部署失败。在启动日志中 grep `capability not loaded`（或你的等价信息）,任何出现都使 readiness probe / rollout 失败。 -2. 将运行时镜像固定为包含 artifact `requires` 中声明的每个包的镜像。 -3. 发布 artifact 时,附带文档化其 `requires` 列表,以便运维核对匹配镜像。 - -## API 表面 - -ObjectOS 通常暴露： - -- 生成的 REST API; -- `/api/v1/auth/*` 下的认证端点; -- 元数据与 i18n 端点; -- 启用能力的服务端点。 - -GraphQL 与 OData 是框架级能力,仅当部署的运行时包包含并启用时方可文档化为受支持。 diff --git a/content/docs/reference/runtime-capabilities.zh-Hant.mdx b/content/docs/reference/runtime-capabilities.zh-Hant.mdx deleted file mode 100644 index 512d15a..0000000 --- a/content/docs/reference/runtime-capabilities.zh-Hant.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 執行時能力 -description: ObjectOS 能從 ObjectStack 框架包載入的能力。 -translation: - source_sha: 75639417a7e7a0851ea5a5fbbd3b6595aa6ba61004d1014e15954d430a9b909f - guide_rev: 1 - mode: auto ---- - -ObjectOS 為每個專案載入一個基礎執行時,然後安裝應用 artifact 宣告的可選能力。 - -## 基礎執行時 - -基礎專案核心包含： - -- ObjectKernel 生命週期與服務註冊; -- ObjectQL 資料引擎; -- 已配置的資料驅動; -- 後設資料服務; -- 應用 artifact 註冊; -- 當配置了 `OS_AUTH_SECRET` 時啟用認證; -- 用於 RBAC、行級安全和欄位安全的 security plugin; -- i18n 服務。 - -## 可選能力 - -Artifact 可在其 `requires` 列表中宣告能力。當映象中存在匹配的框架包時,ObjectOS 會載入它們。 - -| 能力 | 包 | 用途 | -|---|---|---| -| `automation` | `@objectstack/service-automation` | 流程/DAG 執行與自動化節點 | -| `ai` | `@objectstack/service-ai` | LLM 介面卡、對話、工具、SSE 路由 | -| `analytics` | `@objectstack/service-analytics` | Cube、分析查詢、報表資料 | -| `audit` | `@objectstack/plugin-audit` | 審計日誌物件與審計軌跡 | -| `cache` | `@objectstack/service-cache` | 快取抽象與介面卡 | -| `storage` | `@objectstack/service-storage` | 檔案/物件儲存服務 | -| `queue` | `@objectstack/service-queue` | 佇列抽象與 worker | -| `job` | `@objectstack/service-job` | 排程/後臺作業 | -| `realtime` | `@objectstack/service-realtime` | WebSocket 與 pub/sub 即時 | -| `feed` | `@objectstack/service-feed` | 評論、反應、訂閱、動態資訊流 | -| `settings` | `@objectstack/service-settings` | Settings manifest 與 K/V 解析器 | - -如果請求了某能力但映象未包含該包,**ObjectOS 會記錄警告並繼續執行,該能力被停用**。這是有意為之 —— 它使執行時在開發期間即使缺少某個可選包也能啟動 —— 但在**生產中這是真實風險**： - -- 載入到不含 `@objectstack/plugin-audit` 映象的、要求審計的應用,會乾淨地啟動**而不寫任何審計日誌**。合規證據會在無任何錯誤的情況下缺失。 -- 載入到不含 `@objectstack/service-job` 映象的、依賴作業的應用,會乾淨地啟動**而靜默地從不執行排程工作**。 - -**生產清單：** - -1. 將能力警告視為部署失敗。在啟動日誌中 grep `capability not loaded`（或你的等價資訊）,任何出現都使 readiness probe / rollout 失敗。 -2. 將執行時映象固定為包含 artifact `requires` 中宣告的每個包的映象。 -3. 釋出 artifact 時,附帶文件化其 `requires` 列表,以便運維核對匹配映象。 - -## API 表面 - -ObjectOS 通常暴露： - -- 生成的 REST API; -- `/api/v1/auth/*` 下的認證端點; -- 後設資料與 i18n 端點; -- 啟用能力的服務端點。 - -GraphQL 與 OData 是框架級能力,僅當部署的執行時包包含並啟用時方可文件化為受支援。 diff --git a/content/docs/resources/faq.mdx b/content/docs/resources/faq.mdx index 83d67d2..6cec279 100644 --- a/content/docs/resources/faq.mdx +++ b/content/docs/resources/faq.mdx @@ -215,6 +215,6 @@ Include `os doctor` output. Security issues: **security@objectstack.ai**. **Q: Where do I get help from humans?** -A: [GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions), +A: [GitHub Issues](https://github.com/objectstack-ai/objectos/issues), the community Discord, or **sales@objectstack.ai** for commercial support. diff --git a/content/docs/resources/support.mdx b/content/docs/resources/support.mdx index 7cc51c7..97f0248 100644 --- a/content/docs/resources/support.mdx +++ b/content/docs/resources/support.mdx @@ -7,13 +7,13 @@ description: Where to get help, how to report bugs, response expectations. | If you … | Go to | |---|---| -| Have a "how do I" question | [GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions) — community + maintainers | +| Have a "how do I" question | [GitHub Issues](https://github.com/objectstack-ai/objectos/issues) — the public issue tracker for ObjectOS | | Found a bug | [GitHub Issues](https://github.com/objectstack-ai/objectos/issues) — please include version, repro, expected vs actual | | Found a security vulnerability | **security@objectstack.ai** — do **not** open a public issue | | Need commercial support / SLA | **sales@objectstack.ai** | | Want to chat with users + maintainers | [Discord](https://discord.gg/objectstack) (community-run) | | Want to follow releases | Watch [github.com/objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) → Releases | -| Want a paid feature implemented | Open a Discussion → tag with `funding` | +| Want a paid feature implemented | **sales@objectstack.ai** — see [Commercial support & services](#commercial-support--services) | ## Filing a good bug report @@ -40,7 +40,6 @@ diagnoses 80% of misconfigurations on its own. | Security email | 1 business day | | GitHub Issues — bug, with repro | 3 business days for triage, fix on the next release train | | GitHub Issues — feature request | 7 business days for triage | -| GitHub Discussions | Community-driven; maintainers chime in regularly | | Commercial support | Per your support contract | These are best-effort, not SLAs. Commercial support contracts carry