diff --git a/content/de/developer/integration/ai/cocoindex.md b/content/de/developer/integration/ai/cocoindex.md new file mode 100644 index 000000000..738a261de --- /dev/null +++ b/content/de/developer/integration/ai/cocoindex.md @@ -0,0 +1,237 @@ +--- +title: "CocoIndex" +description: "In einem RustFS-Bucket gespeicherte Dokumente mit CocoIndex in Embeddings indexieren." +--- + +In dieser Anleitung verbinden Sie [CocoIndex](https://github.com/cocoindex-io/cocoindex) — die inkrementelle Indexierungs-Engine für KI-Pipelines — mit **RustFS** als Dokumentenquelle. Sie bauen einen Flow, der Markdown-Dateien aus einem Bucket-Präfix auflistet, sie in Chunks teilt, Embeddings erzeugt, die Embeddings in Postgres ablegt und den Index abfragt. Der Ablauf wurde mit CocoIndex `1.0.26` verifiziert, das über einen eigenen S3-Endpunkt aus einem RustFS-Bucket liest. + +Sie benötigen Python 3.11+ und ein Postgres mit der `pgvector`-Erweiterung für Ziel und Zustand des Flows. + +## Architektur + +```mermaid +flowchart LR + RustFS["RustFS :9000"] -->|"S3 source: *.md"| Flow["CocoIndex flow"] + Flow -->|"chunks + embeddings"| PG["Postgres + pgvector"] + Query["semantic query"] --> PG +``` + +CocoIndex liest Quellobjekte über einen selbst erstellten aiobotocore-Client, daher funktioniert jeder S3-kompatible Endpunkt — auch RustFS mit Path-Style-Adressierung. Inkrementelle Updates verarbeiten nur Dateien mit geändertem Inhalt, verschlüsselt über stabile S3-Pfade. + +## 1. Umgebung vorbereiten + +Installieren Sie CocoIndex mit dem S3-Connector und der Embedding-Stack: + +```bash +python3 -m venv .venv +./.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu +./.venv/bin/pip install "cocoindex[amazon_s3]" asyncpg pgvector numpy python-dotenv sentence-transformers +``` + +Laden Sie die Quelldokumente in ein Bucket-Präfix hoch. Ersetzen Sie alle Verbindungsplatzhalter: + +```bash +aws s3 cp ./docs s3://my-bucket/cocoindex-docs/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +upload: docs/rag-basics.md to s3://my-bucket/cocoindex-docs/rag-basics.md +upload: docs/rustfs-overview.md to s3://my-bucket/cocoindex-docs/rustfs-overview.md +``` + +## 2. Den Flow schreiben + +Erstellen Sie die Umgebungsdatei und den Flow. Der S3-Client wird mit gesetztem `AWS_ENDPOINT_URL` erzeugt — aiobotocore honoriert dies für S3-kompatible Endpunkte: + +```ini title=".env" +S3_BUCKET=my-bucket +S3_PREFIX=cocoindex-docs/ +AWS_ENDPOINT_URL=http://:9000 +AWS_ACCESS_KEY_ID= +AWS_SECRET_ACCESS_KEY= +AWS_DEFAULT_REGION=us-east-1 +COCOINDEX_DB=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +POSTGRES_URL=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +``` + +```python title="main.py" +import asyncio, os, sys +from dataclasses import dataclass +from typing import AsyncIterator, Annotated + +import aiobotocore.session +import asyncpg +from dotenv import load_dotenv +from numpy.typing import NDArray +from pgvector.asyncpg import register_vector + +load_dotenv() + +import cocoindex as coco +from cocoindex.connectors import amazon_s3, postgres +from cocoindex.ops.sentence_transformers import SentenceTransformerEmbedder +from cocoindex.ops.text import RecursiveSplitter +from cocoindex.resources.chunk import Chunk +from cocoindex.resources.file import PatternFilePathMatcher + +DATABASE_URL = os.environ["POSTGRES_URL"] +TABLE_NAME = "rustfs_doc_embeddings" +PG_SCHEMA_NAME = "coco_examples" +S3_BUCKET = os.environ["S3_BUCKET"] +S3_PREFIX = os.getenv("S3_PREFIX", "") +EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2" +PG_DB = coco.ContextKey[asyncpg.Pool]("db") +S3_CLIENT = coco.ContextKey[object]("s3_client") +EMBEDDER = coco.ContextKey[SentenceTransformerEmbedder]("embedder", detect_change=True) + +_splitter = RecursiveSplitter() + +@coco.lifespan +async def coco_lifespan(builder: coco.EnvironmentBuilder) -> AsyncIterator[None]: + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + builder.provide(PG_DB, pool) + builder.provide(EMBEDDER, SentenceTransformerEmbedder(EMBED_MODEL)) + session = aiobotocore.session.get_session() + async with session.create_client("s3") as s3_client: + builder.provide(S3_CLIENT, s3_client) + yield + +@dataclass +class DocEmbedding: + id: int + filename: str + text: str + embedding: Annotated[NDArray, EMBEDDER] + +@coco.fn +async def process_chunk(chunk: Chunk, filename: str, table: postgres.TableTarget[DocEmbedding]) -> None: + table.declare_row(row=DocEmbedding( + id=abs(hash(f"{filename}:{chunk.start.char_offset}")) % (10 ** 9), + filename=filename, text=chunk.text, + embedding=await coco.use_context(EMBEDDER).embed(chunk.text), + )) + +@coco.fn(memo=True) +async def process_file(file: amazon_s3.S3File, table: postgres.TableTarget[DocEmbedding]) -> None: + text = await file.read_text() + chunks = _splitter.split(text, chunk_size=2000, chunk_overlap=500, language="markdown") + await coco.map(process_chunk, chunks, file.file_path.path.as_posix(), table) + +@coco.fn +async def app_main() -> None: + target_table = await postgres.mount_table_target( + PG_DB, table_name=TABLE_NAME, + table_schema=await postgres.TableSchema.from_class(DocEmbedding, primary_key=["id"]), + pg_schema_name=PG_SCHEMA_NAME, + ) + client = coco.use_context(S3_CLIENT) + files = amazon_s3.list_objects(client, S3_BUCKET, prefix=S3_PREFIX, + path_matcher=PatternFilePathMatcher(included_patterns=["**/*.md"])) + await coco.mount_each(process_file, files.items(), target_table) + +app = coco.App(coco.AppConfig(name="RustFSDocs"), app_main) + +TOP_K = 5 + + +async def query_once( + pool: asyncpg.Pool, + embedder: SentenceTransformerEmbedder, + query: str, + *, + top_k: int = TOP_K, +) -> None: + query_vec = await embedder.embed(query) + async with pool.acquire() as conn: + rows = await conn.fetch( + f""" + SELECT filename, text, embedding <=> $1 AS distance + FROM "{PG_SCHEMA_NAME}"."{TABLE_NAME}" + ORDER BY distance ASC + LIMIT $2 + """, + query_vec, + top_k, + ) + for r in rows: + score = 1.0 - float(r["distance"]) + print(f"[{score:.3f}] {r['filename']}") + print(f" {r['text']}") + print("---") + + +async def query(initial_query: str | None = None) -> None: + embedder = SentenceTransformerEmbedder(EMBED_MODEL) + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + if initial_query is not None: + await query_once(pool, embedder, initial_query) + return + while True: + q = input("Enter search query (or Enter to quit): ").strip() + if not q: + break + await query_once(pool, embedder, q) + + +if __name__ == "__main__": + initial = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else None + asyncio.run(query(initial)) +``` + +## 3. Den Index aus RustFS bauen + +```bash +set -a && . ./.env && set +a +./.venv/bin/cocoindex update main +``` + +```text +✅ app_main: 1 total | 1 added +✅ process_file: 2 total | 2 added +``` + +Beide Markdown-Dateien wurden aus dem RustFS-Bucket gelesen, in Chunks geteilt und nach Postgres embeddet. Fragen Sie den Index über den Einstieg in `main.py` ab. Das Skript lädt `.env`, embeddet die Frage mit demselben Modell und gibt die nächsten Chunks aus: + +```bash +./.venv/bin/python main.py "what does RustFS expose" +``` + +```text +[0.163] rag-basics.md + Retrieval augmented generation combines a retriever and a generator. +--- +``` + +Die Abfrage trifft Chunks, deren Quelle der Bucket ist — ändern Sie eine Datei in RustFS und führen Sie `cocoindex update main` erneut aus, um nur die Änderung inkrementell neu zu indexieren. + +![CocoIndex-Quelldokumente in der RustFS-Konsole](./images/rustfs-cocoindex-source.png) + +## 4. Anhalten oder Zurücksetzen + +Die indexierten Dokumente löschen: + +```bash +aws s3 rm s3://my-bucket/cocoindex-docs --recursive \ + --endpoint-url http://:9000 +``` + +## Fehlerbehebung + +### `Environment settings must provide Settings.db_path` + +CocoIndex hält seinen eigenen Zustand in Postgres. Setzen Sie `COCOINDEX_DB` (und `POSTGRES_URL` für das Ziel) auf eine Datenbank mit aktivierter `pgvector`-Erweiterung. + +### `InvalidAccessKeyId` oder Connection-Timeouts aus dem Flow + +Die Umgebungsvariablen wurden vor dem Flow-Lauf nicht exportiert (`set -a && . ./.env && set +a`). `AWS_ENDPOINT_URL` muss das Schema enthalten; die Zugangsdaten laufen über das Standardpaar `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`. + +### Der Flow sieht keine Dateien + +Prüfen Sie Präfix und Matcher — `list_objects` durchläuft `S3_PREFIX` und filtert nach `included_patterns`. Bestätigen Sie die Objekte mit `aws s3 ls s3://my-bucket/cocoindex-docs/`. + +## Nächste Schritte + +- Lesen Sie vor weiteren Quellen die [S3-Kompatibilitätshinweise](/administration/protocols/s3). +- Erstellen Sie dedizierte Produktionszugangsdaten mit [Zugangsdatenverwaltung](/security-compliance/iam/access-token). +- Folgen Sie der [CocoIndex-Amazon-S3-Connector-Dokumentation](https://cocoindex.io/docs/connectors/amazon_s3) für Pfad-Matcher, Größenlimits und Live-Updates. diff --git a/content/de/developer/integration/ai/dify.md b/content/de/developer/integration/ai/dify.md new file mode 100644 index 000000000..7c1678625 --- /dev/null +++ b/content/de/developer/integration/ai/dify.md @@ -0,0 +1,135 @@ +--- +title: "Dify" +description: "Dify-Uploads, Knowledge-Base-Dateien und Systemzustand in einem RustFS-Bucket speichern." +--- + +In dieser Anleitung verbinden Sie [Dify](https://github.com/langgenius/dify) — die Open-Source-Plattform für LLM-Anwendungen — über sein OpenDAL-Storage-Backend mit **RustFS**. Sie stellen die Dateispeicherung von lokalen Datenträgern auf einen RustFS-Bucket um, starten den Stack, laden ein Dokument in eine Knowledge Base hoch und bestätigen das Objekt im Bucket. Der Ablauf wurde mit Dify `1.18.0` in Docker Compose verifiziert. + +Sie benötigen Docker Compose. Dieses Setup ist für lokale Integrationstests gedacht, nicht für den Produktivbetrieb. + +## Architektur + +```mermaid +flowchart LR + Console["Console / API"] -->|"files/upload"| RustFS["RustFS :9000"] + RustFS -->|"upload_files, secrets"| API["api / worker"] +``` + +Dify persistiert hochgeladene Dokumente, Knowledge-Base-Dateien und seinen Bootstrap-Secret (`.dify_secret_key`, Workspace-Schlüssel) über das konfigurierte Storage-Backend. Ist das Backend ein Bucket, liegt nichts davon auf Container-Festplatten. + +## 1. Storage für RustFS konfigurieren + +Schalten Sie in `docker/.env` (kopiert aus `.env.example`) OpenDAL auf das S3-Schema um: + +```ini title="docker/.env" +STORAGE_TYPE=opendal +OPENDAL_SCHEME=s3 +OPENDAL_S3_ENDPOINT=http://:9000 +OPENDAL_S3_BUCKET=dify +OPENDAL_S3_ACCESS_KEY_ID= +OPENDAL_S3_SECRET_ACCESS_KEY= +OPENDAL_S3_REGION=us-east-1 +OPENDAL_S3_ENABLE_PATH_STYLE=true +OPENDAL_S3_ROOT=/ +``` + +Legen Sie den Bucket an, bevor Sie den Stack starten: + +```bash +aws s3 mb s3://dify --endpoint-url http://:9000 +``` + +:::note[RustFS an das Compose-Netzwerk anbinden] + +Der Compose-Stack läuft in seinem eigenen Bridge-Netzwerk, und Docker isoliert Bridges voneinander — ein Endpunkt wie `http://172.17.0.2:9000` läuft im `api`-Container in einen Timeout. Verbinden Sie den RustFS-Container mit einem Alias zum Compose-Netzwerk und verwenden Sie den Alias als Endpoint-Host: + +```bash +docker network connect --alias rustfs +``` + +Erstellen Sie den Stack nach der `.env`-Änderung neu — `docker compose restart` übernimmt die alten Umgebungsvariablen. + +::: + +## 2. Stack starten und einrichten + +```bash +cd dify/docker +docker compose up -d +``` + +Warten Sie auf den Health-Check des `api`-Dienstes und legen Sie das Admin-Konto in der Web-UI an (`http://localhost:80`). Dify schreibt sofort seinen Bootstrap-Zustand in den Bucket: + +```bash +aws s3 ls s3://dify/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 14:31:00 65 .dify_secret_key +2026-11-01 14:33:06 1674 privkeys//private.pem +``` + +Secret-Schlüssel und Workspace-Schlüssel liegen jetzt in RustFS — in den Containern bleibt kein relevanter Zustand. + +## 3. Knowledge-Base-Dokument hochladen + +Erstellen Sie eine Knowledge Base im UI und laden Sie ein Dokument hoch. Der Upload landet im Bucket unter `upload_files//`: + +```bash +aws s3 ls s3://dify/upload_files/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 15:25:53 128 upload_files//0ae369a1-70ed-40e8-b3d9-0f12d0b7c699.txt +``` + +Das Objekt erscheint im Moment des Upload-Abschlusses — die Indizierung läuft gegen die Bucket-Kopie. + +![Dify-Uploads in der RustFS-Konsole](./images/rustfs-dify-uploads.png) + +## 4. Anhalten oder Zurücksetzen + +Stack abbauen und die Bucket-Objekte behalten: + +```bash +docker compose down +``` + +Dify-Daten löschen: + +```bash +aws s3 rm s3://dify --recursive \ + --endpoint-url http://:9000 +``` + +:::warning[Beim Zurücksetzen Bind-Mounts leeren] + +Difys Compose-Datei bind-mountet Datenbank und Storage unter `docker/volumes/`. `docker compose down -v` entfernt Bind-Mounts nicht — löschen Sie `docker/volumes/` explizit, wenn Sie einen sauberen Zustand brauchen, sonst überleben das alte Admin-Konto und der Verschlüsselungszustand. + +::: + +## Fehlerbehebung + +### Startup-Logs zeigen `tcp connect error: Connection timed out` gegen den Bucket + +Der Stack erreicht die RustFS-Adresse nicht — Netzwerkisolation zwischen Docker-Bridges. Verbinden Sie RustFS wie in Schritt 1 mit einem Alias zum Compose-Netzwerk. + +### Login schlägt mit `Invalid encrypted data` fehl + +Das Admin-Passwortfeld wird vom Frontend Base64-kodiert; ein Klartext-Passwort über die Console-API scheitert. Nutzen Sie das Web-UI für Konto- und Passwortoperationen, oder kodieren Sie das Feld wie das Frontend. + +### `Default model not found for text-embedding` beim Anlegen von Dokumenten + +Der `high-quality`-Indizierungsmodus braucht einen in Dify konfigurierten Embedding-Modell-Provider. Für einen reinen Storage-Test `economy`-Indizierung verwenden oder zuerst einen Model-Provider konfigurieren. + +### Uploads landen weiterhin auf lokaler Festplatte + +Die Container `api` und `worker` stammen aus der Zeit vor der `.env`-Änderung. Erstellen Sie den ganzen Stack mit `docker compose up -d --force-recreate` neu, damit jeder Dienst die neue Storage-Konfiguration liest. + +## Nächste Schritte + +- Lesen Sie vor großen Knowledge Bases die [S3-Kompatibilitätshinweise](/administration/protocols/s3). +- Erstellen Sie dedizierte Produktionszugangsdaten mit [Zugangsdatenverwaltung](/security-compliance/iam/access-token). +- Folgen Sie der [Dify-Umgebungsvariablen-Referenz](https://docs.dify.ai/en/self-host/deploy/configuration/environments) für die separaten S3-Einstellungen des Plugin-Daemons und Multipart-Tuning auf demselben Bucket. diff --git a/content/de/developer/integration/ai/feast.md b/content/de/developer/integration/ai/feast.md new file mode 100644 index 000000000..b7fa7cbbc --- /dev/null +++ b/content/de/developer/integration/ai/feast.md @@ -0,0 +1,164 @@ +--- +title: "Feast" +description: "Feast-Feature-Registry und Offline-Parquet-Quellen in einem RustFS-Bucket halten." +--- + +In dieser Anleitung verbinden Sie [Feast](https://github.com/feast-dev/feast) — den Open-Source-Feature-Store — mit **RustFS**, und zwar in zwei Speicherrollen zugleich: Die Feature-Registry (`registry.db`) liegt in einem Bucket, und die Offline-Feature-Quelle ist eine Parquet-Datei im selben Bucket. Sie wenden ein Feature-Repository an, materialisieren Features aus RustFS in den Online-Store und lesen sie zurück. Der Ablauf wurde mit Feast `0.67.0` verifiziert. + +Sie benötigen Python 3.10+. Dieses Setup ist für lokale Integrationstests gedacht, nicht für den Produktivbetrieb. + +## Architektur + +```mermaid +flowchart LR + Apply["feast apply"] -->|"registry.db"| RustFS["RustFS :9000"] + RustFS -->|"parquet offline read"| Materialize["feast materialize"] + Materialize -->|"features"| Online["SQLite online store"] + Query["get_online_features"] --> Online +``` + +Der Registry-Store liest und schreibt `registry.db` im Bucket über boto3, und der File-Offline-Store liest Parquet über s3fs — beide honorieren eigene Endpunkte, sodass die gesamte Feature-Historie im Bucket liegt, während der Online-Store lokal bleibt. + +## 1. Feast mit S3-Unterstützung installieren + +Das Basispaket enthält die S3-Clients nicht; installieren Sie sie explizit: + +```bash +python3 -m venv .venv +./.venv/bin/pip install feast boto3 s3fs +``` + +Laden Sie die Offline-Feature-Daten hoch. Ersetzen Sie alle Verbindungsplatzhalter: + +```bash +aws s3 cp driver_stats.parquet s3://my-bucket/feast/driver_stats.parquet \ + --endpoint-url http://:9000 +``` + +## 2. Das Repository konfigurieren + +Erstellen Sie die Repository-Dateien. Die Registry ist eine einfache `s3://`-URI, und der Endpunkt-Override kommt aus der Umgebungsvariablen `FEAST_S3_ENDPOINT_URL`; die Datenquelle trägt ihr eigenes `s3_endpoint_override`: + +```yaml title="feature_store.yaml" +project: rustfs_demo +provider: local +registry: s3://my-bucket/feast/registry.db +offline_store: + type: file +entity_key_serialization_version: 3 +``` + +```python title="features.py" +from datetime import timedelta +from feast import Entity, FeatureView, Field, FileSource +from feast.types import Float32, Int64 + +driver = Entity(name="driver", join_keys=["driver_id"]) +source = FileSource( + name="driver_stats_source", + path="s3://my-bucket/feast/driver_stats.parquet", + timestamp_field="event_timestamp", + s3_endpoint_override="http://:9000", +) +driver_stats = FeatureView( + name="driver_stats", + entities=[driver], + ttl=timedelta(days=1), + schema=[Field(name="conv_rate", dtype=Float32), Field(name="avg_daily_trips", dtype=Int64)], + source=source, +) +``` + +Exportieren Sie Endpunkt und Zugangsdaten für den Registry-Client: + +```bash +export FEAST_S3_ENDPOINT_URL=http://:9000 +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export AWS_DEFAULT_REGION=us-east-1 +``` + +## 3. Repository anwenden und materialisieren + +`feast apply` schreibt `registry.db` in den Bucket; `materialize-incremental` liest die Parquet-Features aus RustFS in den lokalen Online-Store: + +```bash +./.venv/bin/feast apply +./.venv/bin/feast materialize-incremental 2026-11-02T00:00:00Z +``` + +```text +Created entity driver +Created feature view driver_stats +... +driver_stats from 2026-10-31 ... to 2026-11-02 00:00:00+00:00: +``` + +Bestätigen Sie das Registry-Objekt in RustFS: + +```bash +aws s3 ls s3://my-bucket/feast/ \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:57:58 1322 registry.db +2026-11-01 13:56:43 3680 driver_stats.parquet +``` + +![Feast-Registry und Feature-Daten in der RustFS-Konsole](./images/rustfs-feast-registry.png) + +## 4. Features zurücklesen + +```bash +./.venv/bin/python - <<'PY' +from feast import FeatureStore +store = FeatureStore(repo_path=".") +res = store.get_online_features( + features=["driver_stats:conv_rate", "driver_stats:avg_daily_trips"], + entity_rows=[{"driver_id": 101}], +).to_dict() +print("conv_rate:", res["conv_rate"][0]) +print("avg_daily_trips:", res["avg_daily_trips"][0]) +PY +``` + +```text +conv_rate: 0.699999988079071 +avg_daily_trips: 130 +``` + +Die bereitgestellten Features wurden aus der Parquet-Datei materialisiert, die RustFS speichert. + +## 5. Anhalten oder Zurücksetzen + +Die Repository-Objekte löschen: + +```bash +aws s3 rm s3://my-bucket/feast --recursive \ + --endpoint-url http://:9000 +``` + +## Fehlerbehebung + +### `Could not import module 'feast.infra.registry.s3'` + +Der S3-Registry-Store benötigt `boto3`, das das Basispaket von Feast nicht installiert. `pip install boto3` (und `s3fs` für den Offline-Store) löst das. + +### `Install s3fs to access S3` bei der Materialisierung + +Der File-Offline-Store liest Parquet über `s3fs`. Installieren Sie es zusammen mit `boto3` wie in Schritt 1. + +### Der Registry-S3-Store ignoriert den Endpunkt + +Die Registry liest ihren Endpunkt nur aus der Umgebungsvariablen `FEAST_S3_ENDPOINT_URL` — ein einfaches `AWS_ENDPOINT_URL` wird dort nicht honoriert. Die `FileSource` trägt stattdessen ihr eigenes `s3_endpoint_override`; beides ist erforderlich. + +### Eine Deprecation-Warnung zur Entity-Key-Serialisierung + +Setzen Sie `entity_key_serialization_version: 3` in `feature_store.yaml` — Versionen unter 3 werden für neue Online-Stores nicht mehr akzeptiert. + +## Nächste Schritte + +- Lesen Sie, bevor Sie Produktions-Registries auf den Bucket zeigen lassen, die [S3-Kompatibilitätshinweise](/administration/protocols/s3). +- Erstellen Sie dedizierte Produktionszugangsdaten mit [Zugangsdatenverwaltung](/security-compliance/iam/access-token). +- Folgen Sie der [Feast-Dokumentation](https://docs.feast.dev/) für Streaming-Quellen, Feature-Serving und Registry-Alternativen auf demselben Bucket. diff --git a/content/de/developer/integration/ai/images/rustfs-cocoindex-source.png b/content/de/developer/integration/ai/images/rustfs-cocoindex-source.png new file mode 100644 index 000000000..61de59293 Binary files /dev/null and b/content/de/developer/integration/ai/images/rustfs-cocoindex-source.png differ diff --git a/content/de/developer/integration/ai/images/rustfs-dify-uploads.png b/content/de/developer/integration/ai/images/rustfs-dify-uploads.png new file mode 100644 index 000000000..3e4cec9ba Binary files /dev/null and b/content/de/developer/integration/ai/images/rustfs-dify-uploads.png differ diff --git a/content/de/developer/integration/ai/images/rustfs-feast-registry.png b/content/de/developer/integration/ai/images/rustfs-feast-registry.png new file mode 100644 index 000000000..bceea1328 Binary files /dev/null and b/content/de/developer/integration/ai/images/rustfs-feast-registry.png differ diff --git a/content/de/developer/integration/ai/images/rustfs-ragflow-docs.png b/content/de/developer/integration/ai/images/rustfs-ragflow-docs.png new file mode 100644 index 000000000..7ca2e55ee Binary files /dev/null and b/content/de/developer/integration/ai/images/rustfs-ragflow-docs.png differ diff --git a/content/de/developer/integration/ai/meta.json b/content/de/developer/integration/ai/meta.json index f03ec4897..4deb8701f 100644 --- a/content/de/developer/integration/ai/meta.json +++ b/content/de/developer/integration/ai/meta.json @@ -4,6 +4,10 @@ "mlflow", "ray", "sglang", - "vllm" + "vllm", + "dify", + "ragflow", + "cocoindex", + "feast" ] } diff --git a/content/de/developer/integration/ai/ragflow.md b/content/de/developer/integration/ai/ragflow.md new file mode 100644 index 000000000..f51e67991 --- /dev/null +++ b/content/de/developer/integration/ai/ragflow.md @@ -0,0 +1,144 @@ +--- +title: "RAGFlow" +description: "RAGFlow mit hochgeladenen Dokumenten und Workspace-Zustand in einem RustFS-Bucket betreiben." +--- + +In dieser Anleitung verbinden Sie [RAGFlow](https://github.com/infiniflow/ragflow) — die Open-Source-RAG-Engine — mit **RustFS** als Objektspeicher. RAGFlow legt jedes hochgeladene Dokument und Parsing-Artefakt über seine MinIO-kompatible Client-Konfiguration in S3-kompatiblem Storage ab. Sie richten diese Konfiguration auf RustFS, starten den Stack, laden ein Dokument in eine Knowledge Base hoch und bestätigen das Objekt im Bucket. Der Ablauf wurde mit `infiniflow/ragflow:v1.0.0-rc3` und der Infinity-Document-Engine verifiziert. + +Sie benötigen Docker Compose. Dieses Setup ist für lokale Integrationstests gedacht, nicht für den Produktivbetrieb. + +## Architektur + +```mermaid +flowchart LR + Upload["Knowledge base upload"] --> API["RAGFlow API :9380"] + API -->|"documents"| RustFS["RustFS :9000"] + API --> Doc["Infinity / Elasticsearch"] +``` + +Jeder Tenant erhält einen Bucket mit seiner Tenant-ID als Namen, und jede hochgeladene Datei wird zu einem Objekt in diesem Bucket. Das Parsing schreibt weitere Artefakte neben das Quelldokument. + +## 1. Den Stack auf RustFS konfigurieren + +Klonen Sie RAGFlow und bearbeiten Sie `docker/.env`. Wählen Sie die Infinity-Document-Engine und richten Sie den Storage-Client auf RustFS: + +```ini title="docker/.env" +DOC_ENGINE=infinity +MINIO_HOST= +MINIO_USER= +MINIO_PASSWORD= +``` + +Der Abschnitt `minio:` in `docker/service_conf.yaml.template` wird aus diesen Variablen gerendert — dieselben Felder steuern jeden S3-kompatiblen Endpunkt. RAGFlow erzeugt automatisch einen Bucket pro Tenant; ein Voraussetzen ist nicht nötig. + +:::note[RustFS-Container mit Netzwerkalias versehen] + +Der Compose-Stack läuft in seinem eigenen Bridge-Netzwerk, und Docker isoliert Bridges voneinander — die Adresse `172.17.0.x` des RustFS-Containers ist aus dem Stack nicht erreichbar. Verbinden Sie RustFS mit einem Alias zum Compose-Netzwerk und verwenden Sie den Alias als `MINIO_HOST`: + +```bash +docker network connect --alias rustfs ragflow_ragflow +``` + +Ersetzen Sie bei Bedarf auch das mitgelieferte MinIO-Image (von quay.io), falls Ihre Registry es blockiert — der Stack spricht es nicht an, wenn `MINIO_HOST` woandershin zeigt. + +::: + +## 2. Den Stack starten + +```bash +cd ragflow/docker +docker compose -p ragflow up -d +``` + +Warten Sie auf die API und prüfen Sie die vom Server geladene Storage-Konfiguration: + +```bash +docker logs ragflow-cpu 2>&1 | grep "minio:" +``` + +```text +minio: {'user': '...', 'password': '...', 'host': 'rustfs:9000', 'bucket': '', 'prefix_path': ''} +``` + +Ein leerer `bucket` ist erwartet: RAGFlow legt beim ersten Upload automatisch einen Bucket pro Tenant an. + +## 3. Ein Dokument in eine Knowledge Base hochladen + +Erstellen Sie Benutzer und API-Key (in der Web-UI unter `https://localhost:443` oder über die User-API) und nutzen Sie die HTTP-API: + +```bash +curl -s -X POST http://localhost:9380/api/v1/datasets \ + -H "Authorization: Bearer " -H "Content-Type: application/json" \ + -d '{"name":"rustfs-kb"}' + +curl -s -X POST "http://localhost:9380/api/v1/datasets//documents" \ + -H "Authorization: Bearer " \ + -F "file=@rustfs-overview.txt" +``` + +```json +{"code":0,"data":[{"chunk_method":"naive","location":"rustfs-overview.txt","name":"rustfs-overview.txt","run":"UNSTART"}]} +``` + +Bestätigen Sie, dass das Objekt in RustFS gelandet ist — der Tenant-Bucket trägt die Tenant-ID: + +```bash +aws s3 ls s3:/// --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 16:02:41 204 rg-doc.txt +``` + +Lesen Sie das Objekt zurück und vergleichen Sie es mit der hochgeladenen Datei: + +```bash +aws s3 cp s3:///rg-doc.txt - \ + --endpoint-url http://:9000 +``` + +![Hochgeladene RAGFlow-Dokumente in der RustFS-Konsole](./images/rustfs-ragflow-docs.png) + +## 4. Parsen und abrufen + +Das Dokument-Parsing (`PUT /api/v1/datasets/{id}/documents/{doc_id}` mit `{"run":"parse"}`) konsumiert das gespeicherte Objekt aus RustFS und schreibt Chunk-Artefakte daneben. Das Parsing benötigt zusätzlich ein in RAGFlow konfiguriertes Embedding-Modell — dieser Schritt hängt von Ihrem Modell-Setup ab, nicht vom Storage. + +## 5. Anhalten oder Zurücksetzen + +Stack anhalten und die Bucket-Objekte behalten: + +```bash +docker compose -p ragflow stop +``` + +Tenant-Daten löschen: + +```bash +aws s3 rm s3:// --recursive \ + --endpoint-url http://:9000 +``` + +## Fehlerbehebung + +### Upload erfolgreich, aber nichts in RustFS + +Der Server spricht noch das mitgelieferte MinIO an. Prüfen Sie die `minio:`-Zeile im Startlog — zeigt der Host nicht auf Ihren RustFS-Alias, hat die `.env`-Änderung den Container nicht erreicht; erstellen Sie ihn neu mit `docker compose -p ragflow up -d --force-recreate ragflow-cpu`. + +### `tcp connect error: Connection timed out` beim Start + +Die RustFS-Containeradresse ist aus dem Compose-Netzwerk nicht routbar. Verbinden Sie RustFS wie in Schritt 1 mit einem Alias zum Compose-Netzwerk und verwenden Sie den Alias in `MINIO_HOST`. + +### `Authentication error: API key is invalid!` auf `/api/v1` + +Die `/api/v1`-SDK-Routen erwarten einen RAGFlow-API-Key (in der Web-UI erstellt), nicht den Login-Access-Token. `/v1/*`-Routen nutzen die Login-Session. + +### Passwortfehler bei Registrierung oder Login + +RAGFlow erwartet das Passwort vor dem API-Aufruf mit seinem mitgelieferten RSA-Public-Key verschlüsselt — das Web-UI erledigt das. Nutzen Sie das UI zur Kontoerstellung, sofern Sie die clientseitige Verschlüsselung nicht nachbauen. + +## Nächste Schritte + +- Lesen Sie vor umfangreicher Ingestion die [S3-Kompatibilitätshinweise](/administration/protocols/s3). +- Erstellen Sie dedizierte Produktionszugangsdaten mit [Zugangsdatenverwaltung](/security-compliance/iam/access-token). +- Folgen Sie der [RAGFlow-Dokumentation](https://ragflow.io/docs/dev/) für Chunk-Templates, Embedding-Modelle und Agent-Workflows auf demselben Bucket. diff --git a/content/de/developer/integration/database/images/rustfs-qdrant-snapshots.png b/content/de/developer/integration/database/images/rustfs-qdrant-snapshots.png new file mode 100644 index 000000000..de4d1fbfd Binary files /dev/null and b/content/de/developer/integration/database/images/rustfs-qdrant-snapshots.png differ diff --git a/content/de/developer/integration/database/images/rustfs-weaviate-backup.png b/content/de/developer/integration/database/images/rustfs-weaviate-backup.png new file mode 100644 index 000000000..08d28fdcc Binary files /dev/null and b/content/de/developer/integration/database/images/rustfs-weaviate-backup.png differ diff --git a/content/de/developer/integration/database/meta.json b/content/de/developer/integration/database/meta.json index f9323b370..ca2c4510d 100644 --- a/content/de/developer/integration/database/meta.json +++ b/content/de/developer/integration/database/meta.json @@ -9,6 +9,8 @@ "lancedb", "milvus", "trino", - "vitess" + "vitess", + "qdrant", + "weaviate" ] } diff --git a/content/de/developer/integration/database/qdrant.md b/content/de/developer/integration/database/qdrant.md new file mode 100644 index 000000000..cf02dbcde --- /dev/null +++ b/content/de/developer/integration/database/qdrant.md @@ -0,0 +1,133 @@ +--- +title: "Qdrant" +description: "Qdrant-Collection-Snapshots über S3-Backed-Snapshot-Storage in einem RustFS-Bucket speichern." +--- + +In dieser Anleitung verbinden Sie [Qdrant](https://github.com/qdrant/qdrant) — die Open-Source-Vektordatenbank für KI-Suche und RAG — mit **RustFS** als Snapshot-Speicher. Sie aktivieren S3-gestützte Snapshots, erstellen eine Collection mit Vektoren, laden einen Snapshot in den Bucket hoch und stellen ihn auf einem frischen Knoten wieder her. Der Ablauf wurde mit `qdrant/qdrant:v1.20.0` verifiziert, das Snapshots über Path-Style-Adressierung in einem RustFS-Bucket ablegt. + +Sie benötigen Docker. Dieses Setup ist für lokale Integrationstests gedacht, nicht für den Produktivbetrieb. + +## Architektur + +```mermaid +flowchart LR + API["Qdrant REST :6333"] -->|"snapshot"| S3["RustFS :9000"] + S3 -->|"recover"| Fresh["Fresh Qdrant node"] +``` + +Mit `snapshots_storage: s3` wird jeder Collection-Snapshot unter `/snapshots//` in den Bucket hochgeladen. Ein neuer Knoten, der auf denselben Bucket zeigt, kann jede Collection ohne lokale Dateien wiederaufbauen. + +## 1. Qdrant auf RustFS richten + +Konfigurieren Sie den Snapshot-Speicher über Umgebungsvariablen — das Präfix `QDRANT__` bildet den Konfigurationsbaum ab, und `S3_CONFIG__ENDPOINT_URL` ist das Feld für eigene Endpunkte von MinIO-Klasse-Speichern. Der Bucket muss vorab existieren; das Präfix darf leer sein. + +```bash +docker run -d --name qdrant -p 6333:6333 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__SNAPSHOTS_STORAGE=s3 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__BUCKET=my-bucket \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__PREFIX=qdrant \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__REGION=us-east-1 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ACCESS_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__SECRET_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ENDPOINT_URL=http://:9000 \ + qdrant/qdrant:v1.20.0 +``` + +:::note[Pfad QDRANT__STORAGE__SNAPSHOTS_CONFIG verwenden] + +In veröffentlichten Qdrant-Versionen liegen die Einstellungen unter `storage.snapshots_config` (nicht `storage.snapshots`), und der S3-Schlüssel für den Endpunkt heißt `endpoint_url`. Eine eingebundene `custom_config.yaml` mit älteren Schlüsselnamen wird stillschweigend ignoriert — Snapshots landen weiter im lokalen `./snapshots`-Verzeichnis. Prüfen Sie den Wechsel daran, dass das lokale Verzeichnis nach einem Snapshot leer bleibt. + +::: + +## 2. Collection anlegen und Snapshot erzeugen + +Collection erstellen, Punkte einfügen, Snapshot anfordern: + +```bash +curl -s -X PUT http://localhost:6333/collections/demo \ + -H "Content-Type: application/json" \ + -d '{"vectors":{"size":4,"distance":"Dot"}}' + +curl -s -X PUT "http://localhost:6333/collections/demo/points?wait=true" \ + -H "Content-Type: application/json" \ + -d '{"points":[{"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"city":"Berlin"}},{"id":2,"vector":[0.9,0.8,0.7,0.6],"payload":{"city":"Tokyo"}}]}' + +curl -s -X POST http://localhost:6333/collections/demo/snapshots +``` + +```json +{"result":{"name":"demo-8437507706552082-2026-11-01-13-31-15-0.snapshot","size":64512},"status":"ok"} +``` + +Bestätigen Sie, dass das Snapshot-Objekt in RustFS gelandet ist. Ersetzen Sie alle Verbindungsplatzhalter: + +```bash +aws s3 ls s3://my-bucket/qdrant/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:31:15 64512 qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot +``` + +![Qdrant-Snapshot-Objekte in der RustFS-Konsole](./images/rustfs-qdrant-snapshots.png) + +## 3. Auf einem frischen Knoten wiederherstellen + +Ein Snapshot wird in eine Collection mit demselben Namen wiederhergestellt. Setzen Sie den lokalen Knoten zurück (oder starten Sie einen zweiten), der auf denselben Bucket zeigt, laden Sie den Snapshot aus RustFS herunter und übergeben Sie ihn an die Recovery-API: + +```bash +aws s3 cp "s3://my-bucket/qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" . \ + --endpoint-url http://:9000 + +curl -s -X POST "http://localhost:6333/collections/demo/snapshots/upload?priority=snapshot" \ + -F "snapshot=@demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" +``` + +Überprüfen Sie die wiederhergestellten Daten: + +```bash +curl -s -X POST http://localhost:6333/collections/demo/points/scroll \ + -H "Content-Type: application/json" -d '{"limit":2,"with_payload":true}' +``` + +```json +{"result":{"points":[{"id":1,"payload":{"city":"Berlin"}},{"id":2,"payload":{"city":"Tokyo"}}]},"status":"ok"} +``` + +Vektoren und Payloads kommen vollständig aus dem Snapshot, den RustFS gespeichert hat. + +## 4. Anhalten oder Zurücksetzen + +Demo-Umgebung entfernen und die Bucket-Objekte behalten: + +```bash +docker rm -f qdrant +``` + +Gespeicherte Snapshots löschen: + +```bash +aws s3 rm s3://my-bucket/qdrant --recursive \ + --endpoint-url http://:9000 +``` + +## Fehlerbehebung + +### Snapshots erscheinen weiterhin unter `/qdrant/snapshots` im Container + +Der Speicherwechsel wurde nicht übernommen — falscher Env-Pfad oder eine alte Konfigurationsdatei überschreibt ihn. Verwenden Sie exakt die Variablen `QDRANT__STORAGE__SNAPSHOTS_CONFIG__*` aus Schritt 1 und starten Sie den Container neu; prüfen Sie danach, dass das lokale Snapshot-Verzeichnis leer bleibt. + +### `Wrong input: Snapshot is not compatible with existing collection` + +Die Ziel-Collection existiert bereits mit anderem Schema. Löschen Sie die leere oder veraltete Collection vor der Wiederherstellung — die Upload-API erzeugt die Collection aus dem Snapshot. + +### Nach einem Snapshot ist der Bucket leer + +Bucket-Name oder Endpunkt ist falsch. Der Endpunkt muss das Schema enthalten, und der Bucket muss existieren; der Objektschlüssel lautet `/snapshots//.snapshot` — listen Sie rekursiv auf. + +## Nächste Schritte + +- Lesen Sie vor geplanten Snapshot-Backups die [S3-Kompatibilitätshinweise](/administration/protocols/s3). +- Erstellen Sie dedizierte Produktionszugangsdaten mit [Zugangsdatenverwaltung](/security-compliance/iam/access-token). +- Folgen Sie der [Qdrant-Snapshot-Dokumentation](https://qdrant.tech/documentation/snapshots/) für Full-Storage-Snapshots, Shard-Snapshots und Versionskompatibilität auf demselben Bucket. diff --git a/content/de/developer/integration/database/weaviate.md b/content/de/developer/integration/database/weaviate.md new file mode 100644 index 000000000..e72cd5a39 --- /dev/null +++ b/content/de/developer/integration/database/weaviate.md @@ -0,0 +1,148 @@ +--- +title: "Weaviate" +description: "Weaviate-Collections mit dem backup-s3-Modul in einem RustFS-Bucket sichern." +--- + +In dieser Anleitung verbinden Sie [Weaviate](https://github.com/weaviate/weaviate) — die Open-Source-Vektordatenbank für KI-Suche und RAG — über sein `backup-s3`-Modul mit **RustFS**. Sie aktivieren das Modul, erstellen eine Collection mit Vektoren, erzeugen ein Backup im Bucket und stellen es wieder her. Der Ablauf wurde mit `semitechnologies/weaviate:1.31.0` gegen einen RustFS-Bucket verifiziert. + +Sie benötigen Docker. Dieses Setup ist für lokale Integrationstests gedacht, nicht für den Produktivbetrieb. + +## Architektur + +```mermaid +flowchart LR + Weaviate["Weaviate :8080"] -->|"backup create"| RustFS["RustFS :9000"] + RustFS -->|"backup restore"| Weaviate +``` + +Ein Backup schreibt `backup_config.json`, je Klasse eine `backup.json` und Daten-Chunks in das Bucket-Präfix `/`. Die Wiederherstellung liest sie unter denselben Collection-Namen zurück. + +## 1. Das backup-s3-Modul aktivieren + +Starten Sie Weaviate mit dem Modul und seinen S3-Einstellungen. Die Zugangsdaten laufen über die Standard-AWS-Variablen — in Weaviate 1.31 liest das Modul `AWS_ACCESS_KEY_ID` und `AWS_SECRET_ACCESS_KEY`, nicht `BACKUP_S3_ACCESS_KEY_ID`: + +```bash +docker run -d --name weaviate -p 8080:8080 \ + -e QUERY_DEFAULTS_LIMIT=20 \ + -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \ + -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \ + -e ENABLE_MODULES=backup-s3 \ + -e BACKUP_S3_BUCKET=my-bucket \ + -e AWS_REGION=us-east-1 \ + -e AWS_ACCESS_KEY_ID= \ + -e AWS_SECRET_ACCESS_KEY= \ + -e BACKUP_S3_ENDPOINT=:9000 \ + -e BACKUP_S3_USE_SSL=false \ + -e CLUSTER_HOSTNAME=weaviate-demo \ + semitechnologies/weaviate:1.31.0 +``` + +:::note[Endpunktformat und Zugangsdaten] + +`BACKUP_S3_ENDPOINT` erwartet Host und Port ohne Schema — der AWS SDK Go v1-Client hinter dem Modul weist `http://...` mit `Endpoint url cannot have fully qualified paths` zurück. TLS steuert `BACKUP_S3_USE_SSL=false`, die Anfragen erfolgen im Path-Style. Setzen Sie nur `BACKUP_S3_ACCESS_KEY_ID` statt `AWS_ACCESS_KEY_ID`, bleibt der Client anonym, und jeder Backup-Aufruf schlägt mit `Access Denied` fehl. + +::: + +Prüfen Sie, dass das Modul aktiv ist: + +```bash +curl -s http://localhost:8080/v1/meta | grep -o "backup-s3" +``` + +## 2. Collection anlegen und sichern + +In Weaviate 1.31 wird das Schema per `POST /v1/schema` erzeugt. Zwei Objekte einfügen, dann das Backup starten: + +```bash +curl -s -X POST http://localhost:8080/v1/schema \ + -H "Content-Type: application/json" \ + -d '{"class":"Doc","vectorizer":"none","properties":[{"name":"title","dataType":["text"]}]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"RustFS vector backup"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"Weaviate on object storage"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/backups/s3 -H "Content-Type: application/json" \ + -d '{"id":"rustfs-demo"}' +``` + +```json +{"backend":"s3","classes":["Doc"],"id":"rustfs-demo","path":"s3://my-bucket/rustfs-demo","status":"STARTED"} +``` + +Warten Sie auf `SUCCESS` und bestätigen Sie die Objekte in RustFS. Ersetzen Sie alle Verbindungsplatzhalter: + +```bash +curl -s http://localhost:8080/v1/backups/s3/rustfs-demo +aws s3 ls s3://my-bucket/rustfs-demo/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:46:10 304 rustfs-demo/backup_config.json +2026-11-01 13:46:08 1406 rustfs-demo/weaviate-demo/Doc/chunk-1 +2026-11-01 13:46:08 27666 rustfs-demo/weaviate-demo/backup.json +``` + +![Weaviate-Backup-Objekte in der RustFS-Konsole](./images/rustfs-weaviate-backup.png) + +## 3. Wiederherstellen + +Das Backup in Weaviate zurückspielen (für eine saubere Wiederherstellung vorher die Live-Collection löschen): + +```bash +curl -s -X POST http://localhost:8080/v1/backups/s3/rustfs-demo/restore \ + -H "Content-Type: application/json" -d '{}' +``` + +Abfrage der wiederhergestellten Daten: + +```bash +curl -s -X POST http://localhost:8080/v1/graphql -H "Content-Type: application/json" \ + -d '{"query":"{Get{Doc(limit:2){title}}}"}' +``` + +```json +{"data":{"Get":{"Doc":[{"title":"RustFS vector backup"},{"title":"Weaviate on object storage"}]}}} +``` + +## 4. Anhalten oder Zurücksetzen + +Demo-Umgebung entfernen und die Bucket-Objekte behalten: + +```bash +docker rm -f weaviate +``` + +Gespeichertes Backup löschen: + +```bash +aws s3 rm s3://my-bucket/rustfs-demo --recursive \ + --endpoint-url http://:9000 +``` + +## Fehlerbehebung + +### `Endpoint url cannot have fully qualified paths` beim Start + +`BACKUP_S3_ENDPOINT` enthält ein Schema. Verwenden Sie die nackte `host:port`-Form und setzen Sie `BACKUP_S3_USE_SSL=false`. + +### `Access Denied` beim Erzeugen eines Backups + +Das Modul hat keine Zugangsdaten gefunden. In Weaviate 1.31 liest der S3-Client `AWS_ACCESS_KEY_ID` und `AWS_SECRET_ACCESS_KEY` (oder `AWS_ACCESS_KEY`/`AWS_SECRET_KEY`) aus der Umgebung — die Variable `BACKUP_S3_ACCESS_KEY_ID` allein genügt nicht. + +### In der Fehlermeldung erscheint `s3://my-bucket/s3Path/...` + +`BACKUP_S3_PATH` ist in dieser Version ein Bucket-Unterpräfix, kein Path-Style-Schalter — setzen Sie es nicht auf `s3Path`. Der Weaviate-S3-Client verwendet für eigene Endpunkte automatisch Path-Style. + +### `check if backup ... exists` schlägt mit unerwartetem Fehler fehl + +Der Container erreicht RustFS nicht. Prüfen Sie, ob der Endpunkt-Host auflöst und der Bucket existiert. + +## Nächste Schritte + +- Lesen Sie vor automatisierten Backup-Zeitplänen die [S3-Kompatibilitätshinweise](/administration/protocols/s3). +- Erstellen Sie dedizierte Produktionszugangsdaten mit [Zugangsdatenverwaltung](/security-compliance/iam/access-token). +- Folgen Sie der [Weaviate-Backup-Dokumentation](https://docs.weaviate.io/deploy/configuration/backups) für Restore-Filter, rollenbasierte Backups und Dateisystem-Alternativen auf demselben Bucket. diff --git a/content/en/developer/integration/ai/cocoindex.md b/content/en/developer/integration/ai/cocoindex.md new file mode 100644 index 000000000..12d0aceb3 --- /dev/null +++ b/content/en/developer/integration/ai/cocoindex.md @@ -0,0 +1,237 @@ +--- +title: "CocoIndex" +description: "Index documents stored in a RustFS bucket into embeddings with CocoIndex." +--- + +This guide connects [CocoIndex](https://github.com/cocoindex-io/cocoindex) — the incremental indexing engine for AI pipelines — to **RustFS** as the document source. You will build a flow that lists markdown files from a bucket prefix, splits and embeds them, stores the embeddings in Postgres, and queries the index. The workflow was verified with CocoIndex `1.0.26` reading from a RustFS bucket through a custom S3 endpoint. + +You need Python 3.11+ and a Postgres with the `pgvector` extension for the flow's target and state. + +## Architecture + +```mermaid +flowchart LR + RustFS["RustFS :9000"] -->|"S3 source: *.md"| Flow["CocoIndex flow"] + Flow -->|"chunks + embeddings"| PG["Postgres + pgvector"] + Query["semantic query"] --> PG +``` + +CocoIndex reads source objects through an aiobotocore client you create yourself, so any S3-compatible endpoint works — including RustFS with path-style addressing. Incremental updates only reprocess files whose content changed, keyed by stable S3 paths. + +## 1. Prepare the environment + +Install CocoIndex with the S3 connector plus the embedding stack: + +```bash +python3 -m venv .venv +./.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu +./.venv/bin/pip install "cocoindex[amazon_s3]" asyncpg pgvector numpy python-dotenv sentence-transformers +``` + +Upload source documents into a bucket prefix, replacing all connection placeholders: + +```bash +aws s3 cp ./docs s3://my-bucket/cocoindex-docs/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +upload: docs/rag-basics.md to s3://my-bucket/cocoindex-docs/rag-basics.md +upload: docs/rustfs-overview.md to s3://my-bucket/cocoindex-docs/rustfs-overview.md +``` + +## 2. Write the flow + +Create the environment file and the flow. The S3 client is created with `AWS_ENDPOINT_URL` set, which aiobotocore honors for S3-compatible endpoints: + +```ini title=".env" +S3_BUCKET=my-bucket +S3_PREFIX=cocoindex-docs/ +AWS_ENDPOINT_URL=http://:9000 +AWS_ACCESS_KEY_ID= +AWS_SECRET_ACCESS_KEY= +AWS_DEFAULT_REGION=us-east-1 +COCOINDEX_DB=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +POSTGRES_URL=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +``` + +```python title="main.py" +import asyncio, os, sys +from dataclasses import dataclass +from typing import AsyncIterator, Annotated + +import aiobotocore.session +import asyncpg +from dotenv import load_dotenv +from numpy.typing import NDArray +from pgvector.asyncpg import register_vector + +load_dotenv() + +import cocoindex as coco +from cocoindex.connectors import amazon_s3, postgres +from cocoindex.ops.sentence_transformers import SentenceTransformerEmbedder +from cocoindex.ops.text import RecursiveSplitter +from cocoindex.resources.chunk import Chunk +from cocoindex.resources.file import PatternFilePathMatcher + +DATABASE_URL = os.environ["POSTGRES_URL"] +TABLE_NAME = "rustfs_doc_embeddings" +PG_SCHEMA_NAME = "coco_examples" +S3_BUCKET = os.environ["S3_BUCKET"] +S3_PREFIX = os.getenv("S3_PREFIX", "") +EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2" +PG_DB = coco.ContextKey[asyncpg.Pool]("db") +S3_CLIENT = coco.ContextKey[object]("s3_client") +EMBEDDER = coco.ContextKey[SentenceTransformerEmbedder]("embedder", detect_change=True) + +_splitter = RecursiveSplitter() + +@coco.lifespan +async def coco_lifespan(builder: coco.EnvironmentBuilder) -> AsyncIterator[None]: + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + builder.provide(PG_DB, pool) + builder.provide(EMBEDDER, SentenceTransformerEmbedder(EMBED_MODEL)) + session = aiobotocore.session.get_session() + async with session.create_client("s3") as s3_client: + builder.provide(S3_CLIENT, s3_client) + yield + +@dataclass +class DocEmbedding: + id: int + filename: str + text: str + embedding: Annotated[NDArray, EMBEDDER] + +@coco.fn +async def process_chunk(chunk: Chunk, filename: str, table: postgres.TableTarget[DocEmbedding]) -> None: + table.declare_row(row=DocEmbedding( + id=abs(hash(f"{filename}:{chunk.start.char_offset}")) % (10 ** 9), + filename=filename, text=chunk.text, + embedding=await coco.use_context(EMBEDDER).embed(chunk.text), + )) + +@coco.fn(memo=True) +async def process_file(file: amazon_s3.S3File, table: postgres.TableTarget[DocEmbedding]) -> None: + text = await file.read_text() + chunks = _splitter.split(text, chunk_size=2000, chunk_overlap=500, language="markdown") + await coco.map(process_chunk, chunks, file.file_path.path.as_posix(), table) + +@coco.fn +async def app_main() -> None: + target_table = await postgres.mount_table_target( + PG_DB, table_name=TABLE_NAME, + table_schema=await postgres.TableSchema.from_class(DocEmbedding, primary_key=["id"]), + pg_schema_name=PG_SCHEMA_NAME, + ) + client = coco.use_context(S3_CLIENT) + files = amazon_s3.list_objects(client, S3_BUCKET, prefix=S3_PREFIX, + path_matcher=PatternFilePathMatcher(included_patterns=["**/*.md"])) + await coco.mount_each(process_file, files.items(), target_table) + +app = coco.App(coco.AppConfig(name="RustFSDocs"), app_main) + +TOP_K = 5 + + +async def query_once( + pool: asyncpg.Pool, + embedder: SentenceTransformerEmbedder, + query: str, + *, + top_k: int = TOP_K, +) -> None: + query_vec = await embedder.embed(query) + async with pool.acquire() as conn: + rows = await conn.fetch( + f""" + SELECT filename, text, embedding <=> $1 AS distance + FROM "{PG_SCHEMA_NAME}"."{TABLE_NAME}" + ORDER BY distance ASC + LIMIT $2 + """, + query_vec, + top_k, + ) + for r in rows: + score = 1.0 - float(r["distance"]) + print(f"[{score:.3f}] {r['filename']}") + print(f" {r['text']}") + print("---") + + +async def query(initial_query: str | None = None) -> None: + embedder = SentenceTransformerEmbedder(EMBED_MODEL) + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + if initial_query is not None: + await query_once(pool, embedder, initial_query) + return + while True: + q = input("Enter search query (or Enter to quit): ").strip() + if not q: + break + await query_once(pool, embedder, q) + + +if __name__ == "__main__": + initial = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else None + asyncio.run(query(initial)) +``` + +## 3. Build the index from RustFS + +```bash +set -a && . ./.env && set +a +./.venv/bin/cocoindex update main +``` + +```text +✅ app_main: 1 total | 1 added +✅ process_file: 2 total | 2 added +``` + +Both markdown files were read from the RustFS bucket, split, and embedded into Postgres. Query the index with the entrypoint in `main.py`. It loads `.env`, embeds the question with the same model, and prints the nearest chunks: + +```bash +./.venv/bin/python main.py "what does RustFS expose" +``` + +```text +[0.163] rag-basics.md + Retrieval augmented generation combines a retriever and a generator. +--- +``` + +The query hits chunks whose source of truth is the bucket — edit a file in RustFS and re-run `cocoindex update main` to incrementally re-index only the change. + +![CocoIndex source documents in the RustFS Console](./images/rustfs-cocoindex-source.png) + +## 4. Stop or reset + +To delete the indexed documents: + +```bash +aws s3 rm s3://my-bucket/cocoindex-docs --recursive \ + --endpoint-url http://:9000 +``` + +## Troubleshooting + +### `Environment settings must provide Settings.db_path` + +CocoIndex keeps its own state in Postgres. Set `COCOINDEX_DB` (and `POSTGRES_URL` for the target) to a database with the `pgvector` extension enabled. + +### `InvalidAccessKeyId` or connection timeouts from the flow + +The environment variables were not exported before running the flow (`set -a && . ./.env && set +a`). The `AWS_ENDPOINT_URL` must include the scheme; credentials go through the standard `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` pair. + +### The flow sees no files + +Check the prefix and matcher — `list_objects` walks `S3_PREFIX` and filters by `included_patterns`. Confirm the objects exist with `aws s3 ls s3://my-bucket/cocoindex-docs/`. + +## Next steps + +- Review [S3 compatibility notes](/administration/protocols/s3) before wiring additional sources on the same bucket. +- Create dedicated production credentials with [Access Key Management](/security-compliance/iam/access-token). +- Follow the [CocoIndex Amazon S3 connector documentation](https://cocoindex.io/docs/connectors/amazon_s3) for path matchers, size limits, and live updates. diff --git a/content/en/developer/integration/ai/dify.md b/content/en/developer/integration/ai/dify.md new file mode 100644 index 000000000..524a3d1e5 --- /dev/null +++ b/content/en/developer/integration/ai/dify.md @@ -0,0 +1,135 @@ +--- +title: "Dify" +description: "Store Dify uploads, knowledge-base files, and system state in a RustFS bucket." +--- + +This guide connects [Dify](https://github.com/langgenius/dify) — the open-source LLM application platform — to **RustFS** through its OpenDAL storage backend. You will switch the file storage from local disk to a RustFS bucket, start the stack, upload a document into a knowledge base, and confirm the object in the bucket. The workflow was verified with Dify `1.18.0` in Docker Compose. + +You need Docker Compose. This deployment is intended for local integration testing, not production. + +## Architecture + +```mermaid +flowchart LR + Console["Console / API"] -->|"files/upload"| RustFS["RustFS :9000"] + RustFS -->|"upload_files, secrets"| API["api / worker"] +``` + +Dify persists uploaded documents, knowledge-base files, and its bootstrap secret (`​.dify_secret_key`, workspace keys) through the configured storage backend. When the backend is a bucket, none of these live on container disks. + +## 1. Configure storage for RustFS + +In `docker/.env` (copied from `.env.example`), switch OpenDAL to the S3 scheme: + +```ini title="docker/.env" +STORAGE_TYPE=opendal +OPENDAL_SCHEME=s3 +OPENDAL_S3_ENDPOINT=http://:9000 +OPENDAL_S3_BUCKET=dify +OPENDAL_S3_ACCESS_KEY_ID= +OPENDAL_S3_SECRET_ACCESS_KEY= +OPENDAL_S3_REGION=us-east-1 +OPENDAL_S3_ENABLE_PATH_STYLE=true +OPENDAL_S3_ROOT=/ +``` + +Create the bucket before starting the stack: + +```bash +aws s3 mb s3://dify --endpoint-url http://:9000 +``` + +:::note[Attach RustFS to the Compose network] + +The Compose stack lives in its own bridge network, and Docker isolates bridges from each other — an endpoint like `http://172.17.0.2:9000` times out from the `api` container. Attach the RustFS container to the Compose network with an alias and use the alias as the endpoint host: + +```bash +docker network connect --alias rustfs +``` + +Recreate the stack after changing `.env` — `docker compose restart` keeps the old environment variables. + +::: + +## 2. Start the stack and set up + +```bash +cd dify/docker +docker compose up -d +``` + +Wait for the `api` health check to pass, then create the admin account in the web UI (`http://localhost:80`). Dify immediately writes its bootstrap state into the bucket: + +```bash +aws s3 ls s3://dify/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 14:31:00 65 .dify_secret_key +2026-11-01 14:33:06 1674 privkeys//private.pem +``` + +The secret key and workspace keys now live in RustFS — the containers hold no state that matters. + +## 3. Upload a knowledge-base document + +Create a knowledge base in the UI, then upload a document. The upload lands in the bucket under `upload_files//`: + +```bash +aws s3 ls s3://dify/upload_files/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 15:25:53 128 upload_files//0ae369a1-70ed-40e8-b3d9-0f12d0b7c699.txt +``` + +The object appears the moment the upload finishes — indexing runs against the bucket copy. + +![Dify uploads stored in the RustFS Console](./images/rustfs-dify-uploads.png) + +## 4. Stop or reset + +To tear down the stack while keeping the bucket objects: + +```bash +docker compose down +``` + +To delete the Dify data: + +```bash +aws s3 rm s3://dify --recursive \ + --endpoint-url http://:9000 +``` + +:::warning[Wipe bind mounts when resetting] + +Dify's Compose file bind-mounts its database and storage under `docker/volumes/`. `docker compose down -v` does not remove bind mounts — delete `docker/volumes/` explicitly when you need a clean slate, or the old admin account and encryption state survive. + +::: + +## Troubleshooting + +### Startup logs show `tcp connect error: Connection timed out` against the bucket + +The stack cannot reach the RustFS address — network isolation between Docker bridges. Attach RustFS to the Compose network with an alias as shown in step 1. + +### Login fails with `Invalid encrypted data` + +The admin password field is Base64-encoded by the frontend; a raw password over the console API fails. Use the web UI for account and password operations, or encode the field the way the frontend does. + +### `Default model not found for text-embedding` when creating documents + +The `high-quality` indexing mode needs an embedding model provider configured in Dify. Use `economy` indexing for a storage-only test, or configure a model provider first. + +### Uploads still land on local disk + +The `api` and `worker` containers predate the `.env` change. Recreate the whole stack with `docker compose up -d --force-recreate` so every service reads the new storage configuration. + +## Next steps + +- Review [S3 compatibility notes](/administration/protocols/s3) before enabling large knowledge bases. +- Create dedicated production credentials with [Access Key Management](/security-compliance/iam/access-token). +- Follow the [Dify environment variables reference](https://docs.dify.ai/en/self-host/deploy/configuration/environments) for the plugin daemon's separate S3 settings and multipart tuning on the same bucket. diff --git a/content/en/developer/integration/ai/feast.md b/content/en/developer/integration/ai/feast.md new file mode 100644 index 000000000..bd5400515 --- /dev/null +++ b/content/en/developer/integration/ai/feast.md @@ -0,0 +1,164 @@ +--- +title: "Feast" +description: "Keep the Feast feature registry and offline parquet sources in a RustFS bucket." +--- + +This guide connects [Feast](https://github.com/feast-dev/feast) — the open-source feature store — to **RustFS** for two storage roles at once: the feature registry (`registry.db`) lives in a bucket, and the offline feature source is a Parquet file in the same bucket. You will apply a feature repository, materialize features from RustFS into the online store, and read them back. The workflow was verified with Feast `0.67.0`. + +You need Python 3.10+. This deployment is intended for local integration testing, not production. + +## Architecture + +```mermaid +flowchart LR + Apply["feast apply"] -->|"registry.db"| RustFS["RustFS :9000"] + RustFS -->|"parquet offline read"| Materialize["feast materialize"] + Materialize -->|"features"| Online["SQLite online store"] + Query["get_online_features"] --> Online +``` + +The registry store reads and writes `registry.db` in the bucket over boto3, and the file offline store reads Parquet over s3fs — both honor custom endpoints, so the whole feature-history layer is bucket-backed while the online store stays local. + +## 1. Install Feast with S3 support + +The base package omits the S3 clients; install them explicitly: + +```bash +python3 -m venv .venv +./.venv/bin/pip install feast boto3 s3fs +``` + +Upload the offline feature data, replacing all connection placeholders: + +```bash +aws s3 cp driver_stats.parquet s3://my-bucket/feast/driver_stats.parquet \ + --endpoint-url http://:9000 +``` + +## 2. Configure the repository + +Create the repository files. The registry is a plain `s3://` URI and the endpoint override comes from the `FEAST_S3_ENDPOINT_URL` environment variable; the data source carries its own `s3_endpoint_override`: + +```yaml title="feature_store.yaml" +project: rustfs_demo +provider: local +registry: s3://my-bucket/feast/registry.db +offline_store: + type: file +entity_key_serialization_version: 3 +``` + +```python title="features.py" +from datetime import timedelta +from feast import Entity, FeatureView, Field, FileSource +from feast.types import Float32, Int64 + +driver = Entity(name="driver", join_keys=["driver_id"]) +source = FileSource( + name="driver_stats_source", + path="s3://my-bucket/feast/driver_stats.parquet", + timestamp_field="event_timestamp", + s3_endpoint_override="http://:9000", +) +driver_stats = FeatureView( + name="driver_stats", + entities=[driver], + ttl=timedelta(days=1), + schema=[Field(name="conv_rate", dtype=Float32), Field(name="avg_daily_trips", dtype=Int64)], + source=source, +) +``` + +Export the endpoint and credentials for the registry client: + +```bash +export FEAST_S3_ENDPOINT_URL=http://:9000 +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export AWS_DEFAULT_REGION=us-east-1 +``` + +## 3. Apply the repository and materialize + +`feast apply` writes `registry.db` into the bucket; `materialize-incremental` reads the Parquet features from RustFS into the local online store: + +```bash +./.venv/bin/feast apply +./.venv/bin/feast materialize-incremental 2026-11-02T00:00:00Z +``` + +```text +Created entity driver +Created feature view driver_stats +... +driver_stats from 2026-10-31 ... to 2026-11-02 00:00:00+00:00: +``` + +Confirm the registry object in RustFS: + +```bash +aws s3 ls s3://my-bucket/feast/ \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:57:58 1322 registry.db +2026-11-01 13:56:43 3680 driver_stats.parquet +``` + +![Feast registry and feature data in the RustFS Console](./images/rustfs-feast-registry.png) + +## 4. Read the features back + +```bash +./.venv/bin/python - <<'PY' +from feast import FeatureStore +store = FeatureStore(repo_path=".") +res = store.get_online_features( + features=["driver_stats:conv_rate", "driver_stats:avg_daily_trips"], + entity_rows=[{"driver_id": 101}], +).to_dict() +print("conv_rate:", res["conv_rate"][0]) +print("avg_daily_trips:", res["avg_daily_trips"][0]) +PY +``` + +```text +conv_rate: 0.699999988079071 +avg_daily_trips: 130 +``` + +The served features were materialized from the Parquet file that RustFS stores. + +## 5. Stop or reset + +To delete the repository objects: + +```bash +aws s3 rm s3://my-bucket/feast --recursive \ + --endpoint-url http://:9000 +``` + +## Troubleshooting + +### `Could not import module 'feast.infra.registry.s3'` + +The S3 registry store needs `boto3`, which the base Feast package does not install. `pip install boto3` (and `s3fs` for the offline store) resolves it. + +### `Install s3fs to access S3` during materialize + +The file offline store reads Parquet through `s3fs`. Install it alongside `boto3` as shown in step 1. + +### The registry S3 store ignores the endpoint + +The registry reads its endpoint only from the `FEAST_S3_ENDPOINT_URL` environment variable — plain `AWS_ENDPOINT_URL` is not honored there. The `FileSource` carries its own `s3_endpoint_override` instead; both are required. + +### A deprecation warning about entity key serialization + +Set `entity_key_serialization_version: 3` in `feature_store.yaml` — versions below 3 are rejected for new online stores. + +## Next steps + +- Review [S3 compatibility notes](/administration/protocols/s3) before pointing production registries at the bucket. +- Create dedicated production credentials with [Access Key Management](/security-compliance/iam/access-token). +- Follow the [Feast documentation](https://docs.feast.dev/) for streaming sources, feature serving, and registry alternatives on the same bucket. diff --git a/content/en/developer/integration/ai/images/rustfs-cocoindex-source.png b/content/en/developer/integration/ai/images/rustfs-cocoindex-source.png new file mode 100644 index 000000000..61de59293 Binary files /dev/null and b/content/en/developer/integration/ai/images/rustfs-cocoindex-source.png differ diff --git a/content/en/developer/integration/ai/images/rustfs-dify-uploads.png b/content/en/developer/integration/ai/images/rustfs-dify-uploads.png new file mode 100644 index 000000000..3e4cec9ba Binary files /dev/null and b/content/en/developer/integration/ai/images/rustfs-dify-uploads.png differ diff --git a/content/en/developer/integration/ai/images/rustfs-feast-registry.png b/content/en/developer/integration/ai/images/rustfs-feast-registry.png new file mode 100644 index 000000000..bceea1328 Binary files /dev/null and b/content/en/developer/integration/ai/images/rustfs-feast-registry.png differ diff --git a/content/en/developer/integration/ai/images/rustfs-ragflow-docs.png b/content/en/developer/integration/ai/images/rustfs-ragflow-docs.png new file mode 100644 index 000000000..7ca2e55ee Binary files /dev/null and b/content/en/developer/integration/ai/images/rustfs-ragflow-docs.png differ diff --git a/content/en/developer/integration/ai/meta.json b/content/en/developer/integration/ai/meta.json index f03ec4897..4deb8701f 100644 --- a/content/en/developer/integration/ai/meta.json +++ b/content/en/developer/integration/ai/meta.json @@ -4,6 +4,10 @@ "mlflow", "ray", "sglang", - "vllm" + "vllm", + "dify", + "ragflow", + "cocoindex", + "feast" ] } diff --git a/content/en/developer/integration/ai/ragflow.md b/content/en/developer/integration/ai/ragflow.md new file mode 100644 index 000000000..f3006e189 --- /dev/null +++ b/content/en/developer/integration/ai/ragflow.md @@ -0,0 +1,144 @@ +--- +title: "RAGFlow" +description: "Run RAGFlow with uploaded documents and workspace state stored in a RustFS bucket." +--- + +This guide connects [RAGFlow](https://github.com/infiniflow/ragflow) — the open-source RAG engine — to **RustFS** as its object storage. RAGFlow stores every uploaded document and parsed artifact in S3-compatible storage through its MinIO-compatible client configuration. You will point that configuration at RustFS, start the stack, upload a document into a knowledge base, and confirm the object in the bucket. The workflow was verified with `infiniflow/ragflow:v1.0.0-rc3` using the Infinity document engine. + +You need Docker Compose. This deployment is intended for local integration testing, not production. + +## Architecture + +```mermaid +flowchart LR + Upload["Knowledge base upload"] --> API["RAGFlow API :9380"] + API -->|"documents"| RustFS["RustFS :9000"] + API --> Doc["Infinity / Elasticsearch"] +``` + +Each tenant gets a bucket named after its tenant ID, and every uploaded file becomes an object under that bucket. Parsing writes further artifacts next to the source document. + +## 1. Configure the stack for RustFS + +Clone RAGFlow and edit `docker/.env`. Select the Infinity document engine and point the storage client at RustFS: + +```ini title="docker/.env" +DOC_ENGINE=infinity +MINIO_HOST= +MINIO_USER= +MINIO_PASSWORD= +``` + +The `minio:` section of `docker/service_conf.yaml.template` renders from these variables, so the same fields drive any S3-compatible endpoint. RAGFlow creates one bucket per tenant automatically — you do not need to pre-create it. + +:::note[Give the RustFS container a network alias] + +The Compose stack runs in its own bridge network, and Docker isolates bridges from each other, so the RustFS container's `172.17.0.x` address is unreachable from the stack. Attach RustFS to the Compose network with an alias and use the alias as `MINIO_HOST`: + +```bash +docker network connect --alias rustfs ragflow_ragflow +``` + +Also replace the bundled MinIO image (pulled from quay.io) if your registry blocks it — the stack never talks to it when `MINIO_HOST` points elsewhere. + +::: + +## 2. Start the stack + +```bash +cd ragflow/docker +docker compose -p ragflow up -d +``` + +Wait for the API to come up, then confirm the storage configuration the server loaded: + +```bash +docker logs ragflow-cpu 2>&1 | grep "minio:" +``` + +```text +minio: {'user': '...', 'password': '...', 'host': 'rustfs:9000', 'bucket': '', 'prefix_path': ''} +``` + +An empty `bucket` is expected: RAGFlow creates one bucket per tenant on first upload. + +## 3. Upload a document into a knowledge base + +Create a user and an API key (from the web UI at `https://localhost:443`, or through the user API), then use the HTTP API: + +```bash +curl -s -X POST http://localhost:9380/api/v1/datasets \ + -H "Authorization: Bearer " -H "Content-Type: application/json" \ + -d '{"name":"rustfs-kb"}' + +curl -s -X POST "http://localhost:9380/api/v1/datasets//documents" \ + -H "Authorization: Bearer " \ + -F "file=@rustfs-overview.txt" +``` + +```json +{"code":0,"data":[{"chunk_method":"naive","location":"rustfs-overview.txt","name":"rustfs-overview.txt","run":"UNSTART"}]} +``` + +Confirm the object landed in RustFS — the tenant bucket is named after the tenant ID: + +```bash +aws s3 ls s3:/// --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 16:02:41 204 rg-doc.txt +``` + +Read the object back and compare it with the uploaded file: + +```bash +aws s3 cp s3:///rg-doc.txt - \ + --endpoint-url http://:9000 +``` + +![RAGFlow uploaded documents in the RustFS Console](./images/rustfs-ragflow-docs.png) + +## 4. Parse and retrieve + +Document parsing (`PUT /api/v1/datasets/{id}/documents/{doc_id}` with `{"run":"parse"}`) consumes the stored object from RustFS and writes chunk artifacts next to it. Parsing additionally requires an embedding model configured in RAGFlow — that step depends on your model setup, not on storage. + +## 5. Stop or reset + +To tear down the stack while keeping the bucket objects: + +```bash +docker compose -p ragflow stop +``` + +To delete the tenant data: + +```bash +aws s3 rm s3:// --recursive \ + --endpoint-url http://:9000 +``` + +## Troubleshooting + +### Upload succeeds but nothing appears in RustFS + +The server is still talking to the bundled MinIO. Check the `minio:` line in the startup log — if the host is not your RustFS alias, the `.env` edit did not reach the container; recreate it with `docker compose -p ragflow up -d --force-recreate ragflow-cpu`. + +### `tcp connect error: Connection timed out` on startup + +The RustFS container address is not routable from the Compose network. Attach RustFS to the Compose network with an alias as shown in step 1 and use the alias in `MINIO_HOST`. + +### `Authentication error: API key is invalid!` on `/api/v1` + +The `/api/v1` SDK routes accept a RAGFlow API key (created in the web UI), not the login access token. `/v1/*` routes take the login session instead. + +### Password errors on register or login + +RAGFlow expects the password encrypted with its bundled RSA public key before it reaches the API — the web UI does this for you. Use the UI for account creation unless you replicate the client-side encryption. + +## Next steps + +- Review [S3 compatibility notes](/administration/protocols/s3) before enabling large-scale ingestion. +- Create dedicated production credentials with [Access Key Management](/security-compliance/iam/access-token). +- Follow the [RAGFlow documentation](https://ragflow.io/docs/dev/) for chunk templates, embedding models, and agent workflows on the same bucket. diff --git a/content/en/developer/integration/database/images/rustfs-qdrant-snapshots.png b/content/en/developer/integration/database/images/rustfs-qdrant-snapshots.png new file mode 100644 index 000000000..de4d1fbfd Binary files /dev/null and b/content/en/developer/integration/database/images/rustfs-qdrant-snapshots.png differ diff --git a/content/en/developer/integration/database/images/rustfs-weaviate-backup.png b/content/en/developer/integration/database/images/rustfs-weaviate-backup.png new file mode 100644 index 000000000..08d28fdcc Binary files /dev/null and b/content/en/developer/integration/database/images/rustfs-weaviate-backup.png differ diff --git a/content/en/developer/integration/database/meta.json b/content/en/developer/integration/database/meta.json index cbf3ed7b8..3fc496647 100644 --- a/content/en/developer/integration/database/meta.json +++ b/content/en/developer/integration/database/meta.json @@ -9,6 +9,8 @@ "lancedb", "milvus", "trino", - "vitess" + "vitess", + "qdrant", + "weaviate" ] } diff --git a/content/en/developer/integration/database/qdrant.md b/content/en/developer/integration/database/qdrant.md new file mode 100644 index 000000000..76de3e870 --- /dev/null +++ b/content/en/developer/integration/database/qdrant.md @@ -0,0 +1,133 @@ +--- +title: "Qdrant" +description: "Store Qdrant collection snapshots in a RustFS bucket through S3-backed snapshot storage." +--- + +This guide connects [Qdrant](https://github.com/qdrant/qdrant) — the open-source vector database for AI search and RAG — to **RustFS** as its snapshot storage. You will enable S3-backed snapshots, create a collection with vectors, upload a snapshot into the bucket, and recover it onto a fresh node. The workflow was verified with `qdrant/qdrant:v1.20.0` storing snapshots in a RustFS bucket over path-style addressing. + +You need Docker. This deployment is intended for local integration testing, not production. + +## Architecture + +```mermaid +flowchart LR + API["Qdrant REST :6333"] -->|"snapshot"| S3["RustFS :9000"] + S3 -->|"recover"| Fresh["Fresh Qdrant node"] +``` + +With `snapshots_storage: s3`, every collection snapshot is uploaded to the bucket under `/snapshots//`, so a new node pointed at the same bucket can rebuild any collection without local files. + +## 1. Point Qdrant at RustFS + +Configure the snapshot storage through environment variables — the `QDRANT__` prefix maps to the config tree, and `S3_CONFIG__ENDPOINT_URL` is the custom-endpoint field for MinIO-class stores. Create the bucket first if it does not exist; the prefix may be empty. + +```bash +docker run -d --name qdrant -p 6333:6333 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__SNAPSHOTS_STORAGE=s3 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__BUCKET=my-bucket \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__PREFIX=qdrant \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__REGION=us-east-1 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ACCESS_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__SECRET_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ENDPOINT_URL=http://:9000 \ + qdrant/qdrant:v1.20.0 +``` + +:::note[Use the QDRANT__STORAGE__SNAPSHOTS_CONFIG path] + +In released Qdrant versions the settings live under `storage.snapshots_config` (not `storage.snapshots`), and the s3 section key is `endpoint_url`. A mounted `custom_config.yaml` with the older key names is silently ignored — snapshots keep going to the local `./snapshots` directory. Verify the storage switch by checking that the local directory stays empty after a snapshot. + +::: + +## 2. Create a collection and snapshot it + +Create a collection, insert points, and request a snapshot: + +```bash +curl -s -X PUT http://localhost:6333/collections/demo \ + -H "Content-Type: application/json" \ + -d '{"vectors":{"size":4,"distance":"Dot"}}' + +curl -s -X PUT "http://localhost:6333/collections/demo/points?wait=true" \ + -H "Content-Type: application/json" \ + -d '{"points":[{"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"city":"Berlin"}},{"id":2,"vector":[0.9,0.8,0.7,0.6],"payload":{"city":"Tokyo"}}]}' + +curl -s -X POST http://localhost:6333/collections/demo/snapshots +``` + +```json +{"result":{"name":"demo-8437507706552082-2026-11-01-13-31-15-0.snapshot","size":64512},"status":"ok"} +``` + +Confirm the snapshot object landed in RustFS, replacing all connection placeholders: + +```bash +aws s3 ls s3://my-bucket/qdrant/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:31:15 64512 qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot +``` + +![Qdrant snapshot objects in the RustFS Console](./images/rustfs-qdrant-snapshots.png) + +## 3. Recover onto a fresh node + +A snapshot recovers into a collection with the same name. Wipe the local node (or start a second one) pointed at the same bucket, download the snapshot from RustFS, and upload it through the recovery API: + +```bash +aws s3 cp "s3://my-bucket/qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" . \ + --endpoint-url http://:9000 + +curl -s -X POST "http://localhost:6333/collections/demo/snapshots/upload?priority=snapshot" \ + -F "snapshot=@demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" +``` + +Verify the recovered data: + +```bash +curl -s -X POST http://localhost:6333/collections/demo/points/scroll \ + -H "Content-Type: application/json" -d '{"limit":2,"with_payload":true}' +``` + +```json +{"result":{"points":[{"id":1,"payload":{"city":"Berlin"}},{"id":2,"payload":{"city":"Tokyo"}}]},"status":"ok"} +``` + +Both vectors and payloads come back from the snapshot that RustFS stored. + +## 4. Stop or reset + +To tear down the demo while keeping the snapshot objects: + +```bash +docker rm -f qdrant +``` + +To delete the stored snapshots: + +```bash +aws s3 rm s3://my-bucket/qdrant --recursive \ + --endpoint-url http://:9000 +``` + +## Troubleshooting + +### Snapshots still appear under `/qdrant/snapshots` in the container + +The storage switch did not apply — either the env var path is wrong or an old config file overrides it. Use exactly the `QDRANT__STORAGE__SNAPSHOTS_CONFIG__*` variables from step 1 and restart the container; then confirm the local snapshot directory stays empty. + +### `Wrong input: Snapshot is not compatible with existing collection` + +The target collection already exists with a different schema. Delete the empty or stale collection before recovering — the upload API creates the collection from the snapshot. + +### Bucket listing shows nothing after a snapshot + +The bucket name or endpoint is wrong. The endpoint must include the scheme, and the bucket must exist; the object key is `/snapshots//.snapshot`, so list recursively. + +## Next steps + +- Review [S3 compatibility notes](/administration/protocols/s3) before scheduling snapshot backups. +- Create dedicated production credentials with [Access Key Management](/security-compliance/iam/access-token). +- Follow the [Qdrant snapshots documentation](https://qdrant.tech/documentation/snapshots/) for full-storage snapshots, shard-level snapshots, and version compatibility on the same bucket. diff --git a/content/en/developer/integration/database/weaviate.md b/content/en/developer/integration/database/weaviate.md new file mode 100644 index 000000000..6e85595d1 --- /dev/null +++ b/content/en/developer/integration/database/weaviate.md @@ -0,0 +1,148 @@ +--- +title: "Weaviate" +description: "Back up Weaviate collections into a RustFS bucket with the backup-s3 module." +--- + +This guide connects [Weaviate](https://github.com/weaviate/weaviate) — the open-source vector database for AI search and RAG — to **RustFS** through its `backup-s3` module. You will enable the module, create a collection with vectors, create a backup in the bucket, and restore it. The workflow was verified with `semitechnologies/weaviate:1.31.0` backing up to a RustFS bucket. + +You need Docker. This deployment is intended for local integration testing, not production. + +## Architecture + +```mermaid +flowchart LR + Weaviate["Weaviate :8080"] -->|"backup create"| RustFS["RustFS :9000"] + RustFS -->|"backup restore"| Weaviate +``` + +A backup writes `backup_config.json`, per-class `backup.json`, and data chunks into the bucket prefix `/`. Restore reads them back into the same collection names. + +## 1. Enable the backup-s3 module + +Start Weaviate with the module and its S3 settings. Credentials go through the standard AWS variables — in Weaviate 1.31 the module reads `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, not `BACKUP_S3_ACCESS_KEY_ID`: + +```bash +docker run -d --name weaviate -p 8080:8080 \ + -e QUERY_DEFAULTS_LIMIT=20 \ + -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \ + -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \ + -e ENABLE_MODULES=backup-s3 \ + -e BACKUP_S3_BUCKET=my-bucket \ + -e AWS_REGION=us-east-1 \ + -e AWS_ACCESS_KEY_ID= \ + -e AWS_SECRET_ACCESS_KEY= \ + -e BACKUP_S3_ENDPOINT=:9000 \ + -e BACKUP_S3_USE_SSL=false \ + -e CLUSTER_HOSTNAME=weaviate-demo \ + semitechnologies/weaviate:1.31.0 +``` + +:::note[Endpoint format and credentials] + +`BACKUP_S3_ENDPOINT` takes host and port without a scheme — the AWS SDK Go v1 client behind the module rejects `http://...` values with `Endpoint url cannot have fully qualified paths`. TLS is controlled by `BACKUP_S3_USE_SSL=false`, and requests are path-style. Passing `BACKUP_S3_ACCESS_KEY_ID` instead of `AWS_ACCESS_KEY_ID` leaves the client anonymous, and every backup call fails with `Access Denied`. + +::: + +Confirm the module is live: + +```bash +curl -s http://localhost:8080/v1/meta | grep -o "backup-s3" +``` + +## 2. Create a collection and back it up + +Schema creation uses `POST /v1/schema` in Weaviate 1.31. Insert two objects, then start a backup: + +```bash +curl -s -X POST http://localhost:8080/v1/schema \ + -H "Content-Type: application/json" \ + -d '{"class":"Doc","vectorizer":"none","properties":[{"name":"title","dataType":["text"]}]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"RustFS vector backup"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"Weaviate on object storage"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/backups/s3 -H "Content-Type: application/json" \ + -d '{"id":"rustfs-demo"}' +``` + +```json +{"backend":"s3","classes":["Doc"],"id":"rustfs-demo","path":"s3://my-bucket/rustfs-demo","status":"STARTED"} +``` + +Wait for `SUCCESS`, then confirm the objects in RustFS, replacing all connection placeholders: + +```bash +curl -s http://localhost:8080/v1/backups/s3/rustfs-demo +aws s3 ls s3://my-bucket/rustfs-demo/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:46:10 304 rustfs-demo/backup_config.json +2026-11-01 13:46:08 1406 rustfs-demo/weaviate-demo/Doc/chunk-1 +2026-11-01 13:46:08 27666 rustfs-demo/weaviate-demo/backup.json +``` + +![Weaviate backup objects in the RustFS Console](./images/rustfs-weaviate-backup.png) + +## 3. Restore + +Restore the backup into Weaviate (drop the live class first for a clean restore): + +```bash +curl -s -X POST http://localhost:8080/v1/backups/s3/rustfs-demo/restore \ + -H "Content-Type: application/json" -d '{}' +``` + +Query the restored data: + +```bash +curl -s -X POST http://localhost:8080/v1/graphql -H "Content-Type: application/json" \ + -d '{"query":"{Get{Doc(limit:2){title}}}"}' +``` + +```json +{"data":{"Get":{"Doc":[{"title":"RustFS vector backup"},{"title":"Weaviate on object storage"}]}}} +``` + +## 4. Stop or reset + +To tear down the demo while keeping the bucket objects: + +```bash +docker rm -f weaviate +``` + +To delete the stored backup: + +```bash +aws s3 rm s3://my-bucket/rustfs-demo --recursive \ + --endpoint-url http://:9000 +``` + +## Troubleshooting + +### `Endpoint url cannot have fully qualified paths` at startup + +`BACKUP_S3_ENDPOINT` contains a scheme. Use the bare `host:port` form and set `BACKUP_S3_USE_SSL=false`. + +### `Access Denied` when creating a backup + +The module found no credentials. In Weaviate 1.31 the S3 client reads `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (or `AWS_ACCESS_KEY`/`AWS_SECRET_KEY`) from the environment — the `BACKUP_S3_ACCESS_KEY_ID` variable alone is not enough. + +### `s3://my-bucket/s3Path/...` appears in the error + +`BACKUP_S3_PATH` is a bucket sub-prefix in this version, not a path-style switch — do not set it to `s3Path`. Weaviate's S3 client uses path-style addressing automatically for custom endpoints. + +### `check if backup ... exists` fails with an unexpected error + +RustFS is unreachable from the container. Confirm the endpoint host resolves and the bucket exists. + +## Next steps + +- Review [S3 compatibility notes](/administration/protocols/s3) before automating backup schedules. +- Create dedicated production credentials with [Access Key Management](/security-compliance/iam/access-token). +- Follow the [Weaviate backups documentation](https://docs.weaviate.io/deploy/configuration/backups) for restore filters, role-based backups, and filesystem alternatives on the same bucket. diff --git a/content/fr/developer/integration/ai/cocoindex.md b/content/fr/developer/integration/ai/cocoindex.md new file mode 100644 index 000000000..d3cab3e2d --- /dev/null +++ b/content/fr/developer/integration/ai/cocoindex.md @@ -0,0 +1,237 @@ +--- +title: "CocoIndex" +description: "Indexer en embeddings des documents stockés dans un bucket RustFS avec CocoIndex." +--- + +Ce guide connecte [CocoIndex](https://github.com/cocoindex-io/cocoindex) — le moteur d'indexation incrémentale pour pipelines IA — à **RustFS** comme source de documents. Vous allez construire un flux qui liste des fichiers markdown depuis un préfixe de bucket, les découpe et en calcule les embeddings, stocke les embeddings dans Postgres, puis interroge l'index. Le workflow a été vérifié avec CocoIndex `1.0.26` lisant depuis un bucket RustFS via un point de terminaison S3 personnalisé. + +Vous avez besoin de Python 3.11+ et d'un Postgres avec l'extension `pgvector` pour la cible et l'état du flux. + +## Schéma d’architecture + +```mermaid +flowchart LR + RustFS["RustFS :9000"] -->|"S3 source: *.md"| Flow["CocoIndex flow"] + Flow -->|"chunks + embeddings"| PG["Postgres + pgvector"] + Query["semantic query"] --> PG +``` + +CocoIndex lit les objets sources via un client aiobotocore que vous créez vous-même, donc tout point de terminaison compatible S3 fonctionne — y compris RustFS avec l'adressage path-style. Les mises à jour incrémentales ne retraitent que les fichiers dont le contenu a changé, indexés par des chemins S3 stables. + +## 1. Préparer l'environnement + +Installez CocoIndex avec le connecteur S3 et la pile d'embedding : + +```bash +python3 -m venv .venv +./.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu +./.venv/bin/pip install "cocoindex[amazon_s3]" asyncpg pgvector numpy python-dotenv sentence-transformers +``` + +Téléversez les documents sources dans un préfixe de bucket, en remplaçant toutes les valeurs de connexion indicatives : + +```bash +aws s3 cp ./docs s3://my-bucket/cocoindex-docs/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +upload: docs/rag-basics.md to s3://my-bucket/cocoindex-docs/rag-basics.md +upload: docs/rustfs-overview.md to s3://my-bucket/cocoindex-docs/rustfs-overview.md +``` + +## 2. Écrire le flux + +Créez le fichier d'environnement et le flux. Le client S3 est créé avec `AWS_ENDPOINT_URL` défini, que aiobotocore honore pour les points de terminaison compatibles S3 : + +```ini title=".env" +S3_BUCKET=my-bucket +S3_PREFIX=cocoindex-docs/ +AWS_ENDPOINT_URL=http://:9000 +AWS_ACCESS_KEY_ID= +AWS_SECRET_ACCESS_KEY= +AWS_DEFAULT_REGION=us-east-1 +COCOINDEX_DB=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +POSTGRES_URL=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +``` + +```python title="main.py" +import asyncio, os, sys +from dataclasses import dataclass +from typing import AsyncIterator, Annotated + +import aiobotocore.session +import asyncpg +from dotenv import load_dotenv +from numpy.typing import NDArray +from pgvector.asyncpg import register_vector + +load_dotenv() + +import cocoindex as coco +from cocoindex.connectors import amazon_s3, postgres +from cocoindex.ops.sentence_transformers import SentenceTransformerEmbedder +from cocoindex.ops.text import RecursiveSplitter +from cocoindex.resources.chunk import Chunk +from cocoindex.resources.file import PatternFilePathMatcher + +DATABASE_URL = os.environ["POSTGRES_URL"] +TABLE_NAME = "rustfs_doc_embeddings" +PG_SCHEMA_NAME = "coco_examples" +S3_BUCKET = os.environ["S3_BUCKET"] +S3_PREFIX = os.getenv("S3_PREFIX", "") +EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2" +PG_DB = coco.ContextKey[asyncpg.Pool]("db") +S3_CLIENT = coco.ContextKey[object]("s3_client") +EMBEDDER = coco.ContextKey[SentenceTransformerEmbedder]("embedder", detect_change=True) + +_splitter = RecursiveSplitter() + +@coco.lifespan +async def coco_lifespan(builder: coco.EnvironmentBuilder) -> AsyncIterator[None]: + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + builder.provide(PG_DB, pool) + builder.provide(EMBEDDER, SentenceTransformerEmbedder(EMBED_MODEL)) + session = aiobotocore.session.get_session() + async with session.create_client("s3") as s3_client: + builder.provide(S3_CLIENT, s3_client) + yield + +@dataclass +class DocEmbedding: + id: int + filename: str + text: str + embedding: Annotated[NDArray, EMBEDDER] + +@coco.fn +async def process_chunk(chunk: Chunk, filename: str, table: postgres.TableTarget[DocEmbedding]) -> None: + table.declare_row(row=DocEmbedding( + id=abs(hash(f"{filename}:{chunk.start.char_offset}")) % (10 ** 9), + filename=filename, text=chunk.text, + embedding=await coco.use_context(EMBEDDER).embed(chunk.text), + )) + +@coco.fn(memo=True) +async def process_file(file: amazon_s3.S3File, table: postgres.TableTarget[DocEmbedding]) -> None: + text = await file.read_text() + chunks = _splitter.split(text, chunk_size=2000, chunk_overlap=500, language="markdown") + await coco.map(process_chunk, chunks, file.file_path.path.as_posix(), table) + +@coco.fn +async def app_main() -> None: + target_table = await postgres.mount_table_target( + PG_DB, table_name=TABLE_NAME, + table_schema=await postgres.TableSchema.from_class(DocEmbedding, primary_key=["id"]), + pg_schema_name=PG_SCHEMA_NAME, + ) + client = coco.use_context(S3_CLIENT) + files = amazon_s3.list_objects(client, S3_BUCKET, prefix=S3_PREFIX, + path_matcher=PatternFilePathMatcher(included_patterns=["**/*.md"])) + await coco.mount_each(process_file, files.items(), target_table) + +app = coco.App(coco.AppConfig(name="RustFSDocs"), app_main) + +TOP_K = 5 + + +async def query_once( + pool: asyncpg.Pool, + embedder: SentenceTransformerEmbedder, + query: str, + *, + top_k: int = TOP_K, +) -> None: + query_vec = await embedder.embed(query) + async with pool.acquire() as conn: + rows = await conn.fetch( + f""" + SELECT filename, text, embedding <=> $1 AS distance + FROM "{PG_SCHEMA_NAME}"."{TABLE_NAME}" + ORDER BY distance ASC + LIMIT $2 + """, + query_vec, + top_k, + ) + for r in rows: + score = 1.0 - float(r["distance"]) + print(f"[{score:.3f}] {r['filename']}") + print(f" {r['text']}") + print("---") + + +async def query(initial_query: str | None = None) -> None: + embedder = SentenceTransformerEmbedder(EMBED_MODEL) + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + if initial_query is not None: + await query_once(pool, embedder, initial_query) + return + while True: + q = input("Enter search query (or Enter to quit): ").strip() + if not q: + break + await query_once(pool, embedder, q) + + +if __name__ == "__main__": + initial = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else None + asyncio.run(query(initial)) +``` + +## 3. Construire l'index depuis RustFS + +```bash +set -a && . ./.env && set +a +./.venv/bin/cocoindex update main +``` + +```text +✅ app_main: 1 total | 1 added +✅ process_file: 2 total | 2 added +``` + +Les deux fichiers markdown ont été lus depuis le bucket RustFS, découpés et transformés en embeddings dans Postgres. Interrogez l'index via le point d'entrée de `main.py`. Le script charge `.env`, calcule l'embedding de la question avec le même modèle et affiche les chunks les plus proches : + +```bash +./.venv/bin/python main.py "what does RustFS expose" +``` + +```text +[0.163] rag-basics.md + Retrieval augmented generation combines a retriever and a generator. +--- +``` + +La requête atteint des chunks dont la source de vérité est le bucket — modifiez un fichier dans RustFS puis relancez `cocoindex update main` pour ré-indexer incrémentalement le seul changement. + +![Documents sources CocoIndex dans la console RustFS](./images/rustfs-cocoindex-source.png) + +## 4. Arrêter ou réinitialiser + +Supprimer les documents indexés : + +```bash +aws s3 rm s3://my-bucket/cocoindex-docs --recursive \ + --endpoint-url http://:9000 +``` + +## Dépannage + +### `Environment settings must provide Settings.db_path` + +CocoIndex conserve son propre état dans Postgres. Définissez `COCOINDEX_DB` (et `POSTGRES_URL` pour la cible) vers une base avec l'extension `pgvector` activée. + +### `InvalidAccessKeyId` ou des délais d'attente de connexion depuis le flux + +Les variables d'environnement n'ont pas été exportées avant l'exécution (`set -a && . ./.env && set +a`). `AWS_ENDPOINT_URL` doit inclure le schéma ; les identifiants passent par la paire standard `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`. + +### Le flux ne voit aucun fichier + +Vérifiez le préfixe et le filtre — `list_objects` parcourt `S3_PREFIX` et filtre selon `included_patterns`. Confirmez les objets avec `aws s3 ls s3://my-bucket/cocoindex-docs/`. + +## Prochaines étapes + +- Consultez les [notes de compatibilité S3](/administration/protocols/s3) avant de brancher d'autres sources sur le même bucket. +- Créez des identifiants de production dédiés avec la [gestion des clés d'accès](/security-compliance/iam/access-token). +- Suivez la [documentation du connecteur Amazon S3 de CocoIndex](https://cocoindex.io/docs/connectors/amazon_s3) pour les filtres de chemins, les limites de taille et les mises à jour en direct. diff --git a/content/fr/developer/integration/ai/dify.md b/content/fr/developer/integration/ai/dify.md new file mode 100644 index 000000000..cad06c8e1 --- /dev/null +++ b/content/fr/developer/integration/ai/dify.md @@ -0,0 +1,135 @@ +--- +title: "Dify" +description: "Stocker les téléversements Dify, les fichiers de bases de connaissances et l'état système dans un bucket RustFS." +--- + +Ce guide connecte [Dify](https://github.com/langgenius/dify) — la plateforme open source d'applications LLM — à **RustFS** via son backend de stockage OpenDAL. Vous allez basculer le stockage de fichiers du disque local vers un bucket RustFS, démarrer la pile, téléverser un document dans une base de connaissances et confirmer l'objet dans le bucket. Le workflow a été vérifié avec Dify `1.18.0` sous Docker Compose. + +Vous avez besoin de Docker Compose. Ce déploiement est destiné aux tests d'intégration locaux, pas à la production. + +## Schéma d’architecture + +```mermaid +flowchart LR + Console["Console / API"] -->|"files/upload"| RustFS["RustFS :9000"] + RustFS -->|"upload_files, secrets"| API["api / worker"] +``` + +Dify persiste les documents téléversés, les fichiers de bases de connaissances et son secret d'amorçage (`.dify_secret_key`, clés de workspace) via le backend de stockage configuré. Quand le backend est un bucket, rien de tout cela ne réside sur les disques des conteneurs. + +## 1. Configurer le stockage pour RustFS + +Dans `docker/.env` (copié depuis `.env.example`), passez OpenDAL au schéma S3 : + +```ini title="docker/.env" +STORAGE_TYPE=opendal +OPENDAL_SCHEME=s3 +OPENDAL_S3_ENDPOINT=http://:9000 +OPENDAL_S3_BUCKET=dify +OPENDAL_S3_ACCESS_KEY_ID= +OPENDAL_S3_SECRET_ACCESS_KEY= +OPENDAL_S3_REGION=us-east-1 +OPENDAL_S3_ENABLE_PATH_STYLE=true +OPENDAL_S3_ROOT=/ +``` + +Créez le bucket avant de démarrer la pile : + +```bash +aws s3 mb s3://dify --endpoint-url http://:9000 +``` + +:::note[Rattacher RustFS au réseau Compose] + +La pile Compose vit dans son propre réseau bridge, et Docker isole les bridges entre eux — un point de terminaison comme `http://172.17.0.2:9000` expire depuis le conteneur `api`. Rattachez le conteneur RustFS au réseau Compose avec un alias et utilisez l'alias comme hôte du point de terminaison : + +```bash +docker network connect --alias rustfs +``` + +Recréez la pile après avoir modifié `.env` — `docker compose restart` conserve les anciennes variables d'environnement. + +::: + +## 2. Démarrer la pile et l'initialiser + +```bash +cd dify/docker +docker compose up -d +``` + +Attendez le health-check de l'`api`, puis créez le compte administrateur dans l'interface web (`http://localhost:80`). Dify écrit immédiatement son état d'amorçage dans le bucket : + +```bash +aws s3 ls s3://dify/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 14:31:00 65 .dify_secret_key +2026-11-01 14:33:06 1674 privkeys//private.pem +``` + +La clé secrète et les clés du workspace vivent désormais dans RustFS — les conteneurs ne détiennent aucun état important. + +## 3. Téléverser un document dans une base de connaissances + +Créez une base de connaissances dans l'interface, puis téléversez un document. Le téléversement atterrit dans le bucket sous `upload_files//` : + +```bash +aws s3 ls s3://dify/upload_files/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 15:25:53 128 upload_files//0ae369a1-70ed-40e8-b3d9-0f12d0b7c699.txt +``` + +L'objet apparaît dès la fin du téléversement — l'indexation s'exécute sur la copie du bucket. + +![Téléversements Dify stockés dans la console RustFS](./images/rustfs-dify-uploads.png) + +## 4. Arrêter ou réinitialiser + +Pour arrêter la pile en conservant les objets du bucket : + +```bash +docker compose down +``` + +Pour supprimer les données Dify : + +```bash +aws s3 rm s3://dify --recursive \ + --endpoint-url http://:9000 +``` + +:::warning[Vider les bind mounts lors d'une réinitialisation] + +Le fichier Compose de Dify monte par liaison sa base de données et son stockage sous `docker/volumes/`. `docker compose down -v` ne supprime pas les bind mounts — supprimez explicitement `docker/volumes/` pour repartir proprement, sinon l'ancien compte admin et l'état de chiffrement survivent. + +::: + +## Dépannage + +### Les journaux de démarrage montrent `tcp connect error: Connection timed out` vers le bucket + +La pile n'atteint pas l'adresse RustFS — isolation réseau entre bridges Docker. Rattachez RustFS au réseau Compose avec un alias comme à l'étape 1. + +### La connexion échoue avec `Invalid encrypted data` + +Le champ du mot de passe administrateur est encodé en Base64 par le frontend ; un mot de passe brut via l'API console échoue. Utilisez l'interface web pour les opérations de compte, ou encodez le champ comme le fait le frontend. + +### `Default model not found for text-embedding` à la création de documents + +Le mode d'indexation `high-quality` exige un fournisseur de modèle d'embedding configuré dans Dify. Utilisez l'indexation `economy` pour un test de stockage seul, ou configurez d'abord un fournisseur de modèles. + +### Les téléversements arrivent toujours sur le disque local + +Les conteneurs `api` et `worker` datent d'avant la modification du `.env`. Recréez toute la pile avec `docker compose up -d --force-recreate` pour que chaque service lise la nouvelle configuration de stockage. + +## Prochaines étapes + +- Consultez les [notes de compatibilité S3](/administration/protocols/s3) avant d'élargir vos bases de connaissances. +- Créez des identifiants de production dédiés avec la [gestion des clés d'accès](/security-compliance/iam/access-token). +- Suivez la [référence des variables d'environnement Dify](https://docs.dify.ai/en/self-host/deploy/configuration/environments) pour les réglages S3 séparés du démon de plugins et le réglage multipart sur le même bucket. diff --git a/content/fr/developer/integration/ai/feast.md b/content/fr/developer/integration/ai/feast.md new file mode 100644 index 000000000..87f0623a4 --- /dev/null +++ b/content/fr/developer/integration/ai/feast.md @@ -0,0 +1,164 @@ +--- +title: "Feast" +description: "Conserver le registre de features Feast et les sources Parquet hors ligne dans un bucket RustFS." +--- + +Ce guide connecte [Feast](https://github.com/feast-dev/feast) — le feature store open source — à **RustFS** dans deux rôles de stockage simultanés : le registre de features (`registry.db`) vit dans un bucket, et la source de features hors ligne est un fichier Parquet dans le même bucket. Vous allez appliquer un dépôt de features, matérialiser les features depuis RustFS vers le store en ligne, puis les relire. Le workflow a été vérifié avec Feast `0.67.0`. + +Vous avez besoin de Python 3.10+. Ce déploiement est destiné aux tests d'intégration locaux, pas à la production. + +## Schéma d’architecture + +```mermaid +flowchart LR + Apply["feast apply"] -->|"registry.db"| RustFS["RustFS :9000"] + RustFS -->|"parquet offline read"| Materialize["feast materialize"] + Materialize -->|"features"| Online["SQLite online store"] + Query["get_online_features"] --> Online +``` + +Le store de registre lit et écrit `registry.db` dans le bucket via boto3, et le store hors ligne fichier lit le Parquet via s3fs — les deux honorent des points de terminaison personnalisés, si bien que toute la couche d'historique des features est adossée au bucket tandis que le store en ligne reste local. + +## 1. Installer Feast avec le support S3 + +Le paquet de base omet les clients S3 ; installez-les explicitement : + +```bash +python3 -m venv .venv +./.venv/bin/pip install feast boto3 s3fs +``` + +Téléversez les données de features hors ligne, en remplaçant toutes les valeurs de connexion indicatives : + +```bash +aws s3 cp driver_stats.parquet s3://my-bucket/feast/driver_stats.parquet \ + --endpoint-url http://:9000 +``` + +## 2. Configurer le dépôt + +Créez les fichiers du dépôt. Le registre est une simple URI `s3://` et la substitution du point de terminaison provient de la variable d'environnement `FEAST_S3_ENDPOINT_URL` ; la source de données porte son propre `s3_endpoint_override` : + +```yaml title="feature_store.yaml" +project: rustfs_demo +provider: local +registry: s3://my-bucket/feast/registry.db +offline_store: + type: file +entity_key_serialization_version: 3 +``` + +```python title="features.py" +from datetime import timedelta +from feast import Entity, FeatureView, Field, FileSource +from feast.types import Float32, Int64 + +driver = Entity(name="driver", join_keys=["driver_id"]) +source = FileSource( + name="driver_stats_source", + path="s3://my-bucket/feast/driver_stats.parquet", + timestamp_field="event_timestamp", + s3_endpoint_override="http://:9000", +) +driver_stats = FeatureView( + name="driver_stats", + entities=[driver], + ttl=timedelta(days=1), + schema=[Field(name="conv_rate", dtype=Float32), Field(name="avg_daily_trips", dtype=Int64)], + source=source, +) +``` + +Exportez le point de terminaison et les identifiants pour le client du registre : + +```bash +export FEAST_S3_ENDPOINT_URL=http://:9000 +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export AWS_DEFAULT_REGION=us-east-1 +``` + +## 3. Appliquer le dépôt et matérialiser + +`feast apply` écrit `registry.db` dans le bucket ; `materialize-incremental` lit les features Parquet depuis RustFS vers le store en ligne local : + +```bash +./.venv/bin/feast apply +./.venv/bin/feast materialize-incremental 2026-11-02T00:00:00Z +``` + +```text +Created entity driver +Created feature view driver_stats +... +driver_stats from 2026-10-31 ... to 2026-11-02 00:00:00+00:00: +``` + +Confirmez l'objet du registre dans RustFS : + +```bash +aws s3 ls s3://my-bucket/feast/ \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:57:58 1322 registry.db +2026-11-01 13:56:43 3680 driver_stats.parquet +``` + +![Registre Feast et données de features dans la console RustFS](./images/rustfs-feast-registry.png) + +## 4. Relire les features + +```bash +./.venv/bin/python - <<'PY' +from feast import FeatureStore +store = FeatureStore(repo_path=".") +res = store.get_online_features( + features=["driver_stats:conv_rate", "driver_stats:avg_daily_trips"], + entity_rows=[{"driver_id": 101}], +).to_dict() +print("conv_rate:", res["conv_rate"][0]) +print("avg_daily_trips:", res["avg_daily_trips"][0]) +PY +``` + +```text +conv_rate: 0.699999988079071 +avg_daily_trips: 130 +``` + +Les features servies ont été matérialisées depuis le fichier Parquet que RustFS stocke. + +## 5. Arrêter ou réinitialiser + +Supprimer les objets du dépôt : + +```bash +aws s3 rm s3://my-bucket/feast --recursive \ + --endpoint-url http://:9000 +``` + +## Dépannage + +### `Could not import module 'feast.infra.registry.s3'` + +Le store de registre S3 a besoin de `boto3`, que le paquet Feast de base n'installe pas. `pip install boto3` (et `s3fs` pour le store hors ligne) résout le problème. + +### `Install s3fs to access S3` pendant la matérialisation + +Le store hors ligne fichier lit le Parquet via `s3fs`. Installez-le avec `boto3` comme à l'étape 1. + +### Le store de registre S3 ignore le point de terminaison + +Le registre ne lit son point de terminaison que depuis la variable d'environnement `FEAST_S3_ENDPOINT_URL` — un simple `AWS_ENDPOINT_URL` n'y est pas honoré. La `FileSource` porte son propre `s3_endpoint_override` ; les deux sont nécessaires. + +### Un avertissement de dépréciation sur la sérialisation des clés d'entité + +Réglez `entity_key_serialization_version: 3` dans `feature_store.yaml` — les versions inférieures à 3 sont refusées pour les nouveaux stores en ligne. + +## Prochaines étapes + +- Consultez les [notes de compatibilité S3](/administration/protocols/s3) avant de pointer des registres de production vers le bucket. +- Créez des identifiants de production dédiés avec la [gestion des clés d'accès](/security-compliance/iam/access-token). +- Suivez la [documentation Feast](https://docs.feast.dev/) pour les sources en flux, le service de features et les alternatives de registre sur le même bucket. diff --git a/content/fr/developer/integration/ai/images/rustfs-cocoindex-source.png b/content/fr/developer/integration/ai/images/rustfs-cocoindex-source.png new file mode 100644 index 000000000..61de59293 Binary files /dev/null and b/content/fr/developer/integration/ai/images/rustfs-cocoindex-source.png differ diff --git a/content/fr/developer/integration/ai/images/rustfs-dify-uploads.png b/content/fr/developer/integration/ai/images/rustfs-dify-uploads.png new file mode 100644 index 000000000..3e4cec9ba Binary files /dev/null and b/content/fr/developer/integration/ai/images/rustfs-dify-uploads.png differ diff --git a/content/fr/developer/integration/ai/images/rustfs-feast-registry.png b/content/fr/developer/integration/ai/images/rustfs-feast-registry.png new file mode 100644 index 000000000..bceea1328 Binary files /dev/null and b/content/fr/developer/integration/ai/images/rustfs-feast-registry.png differ diff --git a/content/fr/developer/integration/ai/images/rustfs-ragflow-docs.png b/content/fr/developer/integration/ai/images/rustfs-ragflow-docs.png new file mode 100644 index 000000000..7ca2e55ee Binary files /dev/null and b/content/fr/developer/integration/ai/images/rustfs-ragflow-docs.png differ diff --git a/content/fr/developer/integration/ai/meta.json b/content/fr/developer/integration/ai/meta.json index 02233008e..bfc5c3e84 100644 --- a/content/fr/developer/integration/ai/meta.json +++ b/content/fr/developer/integration/ai/meta.json @@ -4,6 +4,10 @@ "mlflow", "ray", "sglang", - "vllm" + "vllm", + "dify", + "ragflow", + "cocoindex", + "feast" ] } diff --git a/content/fr/developer/integration/ai/ragflow.md b/content/fr/developer/integration/ai/ragflow.md new file mode 100644 index 000000000..f4247af17 --- /dev/null +++ b/content/fr/developer/integration/ai/ragflow.md @@ -0,0 +1,144 @@ +--- +title: "RAGFlow" +description: "Exécuter RAGFlow avec les documents téléversés et l'état du workspace dans un bucket RustFS." +--- + +Ce guide connecte [RAGFlow](https://github.com/infiniflow/ragflow) — le moteur RAG open source — à **RustFS** comme stockage objet. RAGFlow place chaque document téléversé et chaque artefact d'analyse dans un stockage compatible S3 via sa configuration client compatible MinIO. Vous allez pointer cette configuration vers RustFS, démarrer la pile, téléverser un document dans une base de connaissances et confirmer l'objet dans le bucket. Le workflow a été vérifié avec `infiniflow/ragflow:v1.0.0-rc3` et le moteur de documents Infinity. + +Vous avez besoin de Docker Compose. Ce déploiement est destiné aux tests d'intégration locaux, pas à la production. + +## Schéma d’architecture + +```mermaid +flowchart LR + Upload["Knowledge base upload"] --> API["RAGFlow API :9380"] + API -->|"documents"| RustFS["RustFS :9000"] + API --> Doc["Infinity / Elasticsearch"] +``` + +Chaque tenant obtient un bucket nommé d'après son identifiant de tenant, et chaque fichier téléversé devient un objet dans ce bucket. L'analyse écrit des artefacts supplémentaires à côté du document source. + +## 1. Configurer la pile pour RustFS + +Clonez RAGFlow et modifiez `docker/.env`. Choisissez le moteur de documents Infinity et pointez le client de stockage vers RustFS : + +```ini title="docker/.env" +DOC_ENGINE=infinity +MINIO_HOST= +MINIO_USER= +MINIO_PASSWORD= +``` + +La section `minio:` de `docker/service_conf.yaml.template` est rendue à partir de ces variables — les mêmes champs pilotent n'importe quel point de terminaison compatible S3. RAGFlow crée automatiquement un bucket par tenant au premier téléversement ; inutile de le créer au préalable. + +:::note[Donner un alias réseau au conteneur RustFS] + +La pile Compose vit dans son propre réseau bridge, et Docker isole les bridges entre eux — l'adresse `172.17.0.x` du conteneur RustFS est injoignable depuis la pile. Rattachez RustFS au réseau Compose avec un alias et utilisez l'alias comme `MINIO_HOST` : + +```bash +docker network connect --alias rustfs ragflow_ragflow +``` + +Remplacez aussi l'image MinIO fournie (tirée de quay.io) si votre registre la bloque — la pile ne lui parle pas quand `MINIO_HOST` pointe ailleurs. + +::: + +## 2. Démarrer la pile + +```bash +cd ragflow/docker +docker compose -p ragflow up -d +``` + +Attendez que l'API démarre, puis confirmez la configuration de stockage chargée par le serveur : + +```bash +docker logs ragflow-cpu 2>&1 | grep "minio:" +``` + +```text +minio: {'user': '...', 'password': '...', 'host': 'rustfs:9000', 'bucket': '', 'prefix_path': ''} +``` + +Un `bucket` vide est attendu : RAGFlow crée un bucket par tenant au premier téléversement. + +## 3. Téléverser un document dans une base de connaissances + +Créez un utilisateur et une clé API (depuis l'interface web sur `https://localhost:443`, ou via l'API utilisateur), puis utilisez l'API HTTP : + +```bash +curl -s -X POST http://localhost:9380/api/v1/datasets \ + -H "Authorization: Bearer " -H "Content-Type: application/json" \ + -d '{"name":"rustfs-kb"}' + +curl -s -X POST "http://localhost:9380/api/v1/datasets//documents" \ + -H "Authorization: Bearer " \ + -F "file=@rustfs-overview.txt" +``` + +```json +{"code":0,"data":[{"chunk_method":"naive","location":"rustfs-overview.txt","name":"rustfs-overview.txt","run":"UNSTART"}]} +``` + +Confirmez que l'objet a atterri dans RustFS — le bucket du tenant porte son identifiant : + +```bash +aws s3 ls s3:/// --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 16:02:41 204 rg-doc.txt +``` + +Relisez l'objet et comparez-le au fichier téléversé : + +```bash +aws s3 cp s3:///rg-doc.txt - \ + --endpoint-url http://:9000 +``` + +![Documents téléversés RAGFlow dans la console RustFS](./images/rustfs-ragflow-docs.png) + +## 4. Analyser et récupérer + +L'analyse des documents (`PUT /api/v1/datasets/{id}/documents/{doc_id}` avec `{"run":"parse"}`) consomme l'objet stocké depuis RustFS et écrit les artefacts de chunks à côté. L'analyse nécessite en outre un modèle d'embedding configuré dans RAGFlow — cette étape dépend de votre configuration de modèles, pas du stockage. + +## 5. Arrêter ou réinitialiser + +Pour arrêter la pile en conservant les objets du bucket : + +```bash +docker compose -p ragflow stop +``` + +Pour supprimer les données du tenant : + +```bash +aws s3 rm s3:// --recursive \ + --endpoint-url http://:9000 +``` + +## Dépannage + +### Le téléversement réussit mais rien n'apparaît dans RustFS + +Le serveur parle encore au MinIO fourni. Consultez la ligne `minio:` du journal de démarrage — si l'hôte n'est pas votre alias RustFS, la modification du `.env` n'a pas atteint le conteneur ; recréez-le avec `docker compose -p ragflow up -d --force-recreate ragflow-cpu`. + +### `tcp connect error: Connection timed out` au démarrage + +L'adresse du conteneur RustFS n'est pas routable depuis le réseau Compose. Rattachez RustFS au réseau Compose avec un alias comme à l'étape 1 et utilisez l'alias dans `MINIO_HOST`. + +### `Authentication error: API key is invalid!` sur `/api/v1` + +Les routes SDK `/api/v1` acceptent une clé API RAGFlow (créée dans l'interface web), pas le jeton d'accès de connexion. Les routes `/v1/*` utilisent la session de connexion. + +### Erreurs de mot de passe à l'inscription ou la connexion + +RAGFlow attend le mot de passe chiffré avec sa clé publique RSA fournie avant d'atteindre l'API — l'interface web s'en charge. Utilisez l'interface pour créer les comptes, sauf à reproduire le chiffrement côté client. + +## Prochaines étapes + +- Consultez les [notes de compatibilité S3](/administration/protocols/s3) avant une ingestion à grande échelle. +- Créez des identifiants de production dédiés avec la [gestion des clés d'accès](/security-compliance/iam/access-token). +- Suivez la [documentation RAGFlow](https://ragflow.io/docs/dev/) pour les modèles de chunks, les modèles d'embedding et les workflows d'agents sur le même bucket. diff --git a/content/fr/developer/integration/database/images/rustfs-qdrant-snapshots.png b/content/fr/developer/integration/database/images/rustfs-qdrant-snapshots.png new file mode 100644 index 000000000..de4d1fbfd Binary files /dev/null and b/content/fr/developer/integration/database/images/rustfs-qdrant-snapshots.png differ diff --git a/content/fr/developer/integration/database/images/rustfs-weaviate-backup.png b/content/fr/developer/integration/database/images/rustfs-weaviate-backup.png new file mode 100644 index 000000000..08d28fdcc Binary files /dev/null and b/content/fr/developer/integration/database/images/rustfs-weaviate-backup.png differ diff --git a/content/fr/developer/integration/database/meta.json b/content/fr/developer/integration/database/meta.json index 60ba9a6fe..9c0905457 100644 --- a/content/fr/developer/integration/database/meta.json +++ b/content/fr/developer/integration/database/meta.json @@ -9,6 +9,8 @@ "lancedb", "milvus", "trino", - "vitess" + "vitess", + "qdrant", + "weaviate" ] } diff --git a/content/fr/developer/integration/database/qdrant.md b/content/fr/developer/integration/database/qdrant.md new file mode 100644 index 000000000..70184500d --- /dev/null +++ b/content/fr/developer/integration/database/qdrant.md @@ -0,0 +1,133 @@ +--- +title: "Qdrant" +description: "Stocker les snapshots de collections Qdrant dans un bucket RustFS via le stockage de snapshots S3." +--- + +Ce guide connecte [Qdrant](https://github.com/qdrant/qdrant) — la base de données vectorielle open source pour la recherche IA et le RAG — à **RustFS** comme stockage de snapshots. Vous allez activer le stockage de snapshots S3, créer une collection avec des vecteurs, téléverser un snapshot dans le bucket, puis le restaurer sur un nœud neuf. Le workflow a été vérifié avec `qdrant/qdrant:v1.20.0` écrivant ses snapshots dans un bucket RustFS via l'adressage path-style. + +Vous avez besoin de Docker. Ce déploiement est destiné aux tests d'intégration locaux, pas à la production. + +## Schéma d’architecture + +```mermaid +flowchart LR + API["Qdrant REST :6333"] -->|"snapshot"| S3["RustFS :9000"] + S3 -->|"recover"| Fresh["Fresh Qdrant node"] +``` + +Avec `snapshots_storage: s3`, chaque snapshot de collection est téléversé dans le bucket sous `/snapshots//` ; un nœud neuf pointant vers le même bucket peut reconstruire n'importe quelle collection sans fichiers locaux. + +## 1. Pointer Qdrant vers RustFS + +Configurez le stockage de snapshots via des variables d'environnement — le préfixe `QDRANT__` mappe l'arbre de configuration, et `S3_CONFIG__ENDPOINT_URL` est le champ de point de terminaison personnalisé pour les stockages de classe MinIO. Le bucket doit exister au préalable ; le préfixe peut être vide. + +```bash +docker run -d --name qdrant -p 6333:6333 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__SNAPSHOTS_STORAGE=s3 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__BUCKET=my-bucket \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__PREFIX=qdrant \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__REGION=us-east-1 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ACCESS_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__SECRET_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ENDPOINT_URL=http://:9000 \ + qdrant/qdrant:v1.20.0 +``` + +:::note[Utiliser le chemin QDRANT__STORAGE__SNAPSHOTS_CONFIG] + +Dans les versions publiées de Qdrant, les réglages vivent sous `storage.snapshots_config` (pas `storage.snapshots`), et la clé s3 du point de terminaison est `endpoint_url`. Un `custom_config.yaml` monté avec d'anciens noms de clés est ignoré silencieusement — les snapshots continuent d'aller dans le répertoire local `./snapshots`. Vérifiez la bascule en constatant que le répertoire local reste vide après un snapshot. + +::: + +## 2. Créer une collection et prendre un snapshot + +Créez une collection, insérez des points, demandez un snapshot : + +```bash +curl -s -X PUT http://localhost:6333/collections/demo \ + -H "Content-Type: application/json" \ + -d '{"vectors":{"size":4,"distance":"Dot"}}' + +curl -s -X PUT "http://localhost:6333/collections/demo/points?wait=true" \ + -H "Content-Type: application/json" \ + -d '{"points":[{"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"city":"Berlin"}},{"id":2,"vector":[0.9,0.8,0.7,0.6],"payload":{"city":"Tokyo"}}]}' + +curl -s -X POST http://localhost:6333/collections/demo/snapshots +``` + +```json +{"result":{"name":"demo-8437507706552082-2026-11-01-13-31-15-0.snapshot","size":64512},"status":"ok"} +``` + +Confirmez que l'objet snapshot a atterri dans RustFS, en remplaçant toutes les valeurs de connexion indicatives : + +```bash +aws s3 ls s3://my-bucket/qdrant/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:31:15 64512 qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot +``` + +![Objets de snapshot Qdrant dans la console RustFS](./images/rustfs-qdrant-snapshots.png) + +## 3. Restaurer sur un nœud neuf + +Un snapshot se restaure dans une collection de même nom. Réinitialisez le nœud local (ou démarrez-en un second) pointant vers le même bucket, téléchargez le snapshot depuis RustFS et passez-le à l'API de récupération : + +```bash +aws s3 cp "s3://my-bucket/qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" . \ + --endpoint-url http://:9000 + +curl -s -X POST "http://localhost:6333/collections/demo/snapshots/upload?priority=snapshot" \ + -F "snapshot=@demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" +``` + +Vérifiez les données restaurées : + +```bash +curl -s -X POST http://localhost:6333/collections/demo/points/scroll \ + -H "Content-Type: application/json" -d '{"limit":2,"with_payload":true}' +``` + +```json +{"result":{"points":[{"id":1,"payload":{"city":"Berlin"}},{"id":2,"payload":{"city":"Tokyo"}}]},"status":"ok"} +``` + +Vecteurs et payloads reviennent intégralement depuis le snapshot stocké par RustFS. + +## 4. Arrêter ou réinitialiser + +Pour démonter la démo tout en conservant les objets du bucket : + +```bash +docker rm -f qdrant +``` + +Pour supprimer les snapshots stockés : + +```bash +aws s3 rm s3://my-bucket/qdrant --recursive \ + --endpoint-url http://:9000 +``` + +## Dépannage + +### Les snapshots apparaissent toujours sous `/qdrant/snapshots` dans le conteneur + +La bascule de stockage n'a pas été appliquée — chemin de variable erroné ou ancien fichier de config qui écrase. Utilisez exactement les variables `QDRANT__STORAGE__SNAPSHOTS_CONFIG__*` de l'étape 1 et redémarrez le conteneur ; vérifiez ensuite que le répertoire local des snapshots reste vide. + +### `Wrong input: Snapshot is not compatible with existing collection` + +La collection cible existe déjà avec un schéma différent. Supprimez la collection vide ou périmée avant de restaurer — l'API de téléversement crée la collection à partir du snapshot. + +### Le bucket reste vide après un snapshot + +Nom de bucket ou point de terminaison erroné. Le point de terminaison doit inclure le schéma et le bucket doit exister ; la clé d'objet est `/snapshots//.snapshot` — listez récursivement. + +## Prochaines étapes + +- Consultez les [notes de compatibilité S3](/administration/protocols/s3) avant de planifier des sauvegardes par snapshot. +- Créez des identifiants de production dédiés avec la [gestion des clés d'accès](/security-compliance/iam/access-token). +- Suivez la [documentation des snapshots Qdrant](https://qdrant.tech/documentation/snapshots/) pour les snapshots de stockage complet, les snapshots de shards et la compatibilité des versions sur le même bucket. diff --git a/content/fr/developer/integration/database/weaviate.md b/content/fr/developer/integration/database/weaviate.md new file mode 100644 index 000000000..d7035fb13 --- /dev/null +++ b/content/fr/developer/integration/database/weaviate.md @@ -0,0 +1,148 @@ +--- +title: "Weaviate" +description: "Sauvegarder les collections Weaviate dans un bucket RustFS avec le module backup-s3." +--- + +Ce guide connecte [Weaviate](https://github.com/weaviate/weaviate) — la base de données vectorielle open source pour la recherche IA et le RAG — à **RustFS** via son module `backup-s3`. Vous allez activer le module, créer une collection avec des vecteurs, créer une sauvegarde dans le bucket, puis la restaurer. Le workflow a été vérifié avec `semitechnologies/weaviate:1.31.0` sauvegardant dans un bucket RustFS. + +Vous avez besoin de Docker. Ce déploiement est destiné aux tests d'intégration locaux, pas à la production. + +## Schéma d’architecture + +```mermaid +flowchart LR + Weaviate["Weaviate :8080"] -->|"backup create"| RustFS["RustFS :9000"] + RustFS -->|"backup restore"| Weaviate +``` + +Une sauvegarde écrit `backup_config.json`, un `backup.json` par classe et des blocs de données dans le préfixe du bucket `/`. La restauration les relit sous les mêmes noms de collection. + +## 1. Activer le module backup-s3 + +Démarrez Weaviate avec le module et ses réglages S3. Les identifiants passent par les variables AWS standard — dans Weaviate 1.31, le module lit `AWS_ACCESS_KEY_ID` et `AWS_SECRET_ACCESS_KEY`, pas `BACKUP_S3_ACCESS_KEY_ID` : + +```bash +docker run -d --name weaviate -p 8080:8080 \ + -e QUERY_DEFAULTS_LIMIT=20 \ + -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \ + -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \ + -e ENABLE_MODULES=backup-s3 \ + -e BACKUP_S3_BUCKET=my-bucket \ + -e AWS_REGION=us-east-1 \ + -e AWS_ACCESS_KEY_ID= \ + -e AWS_SECRET_ACCESS_KEY= \ + -e BACKUP_S3_ENDPOINT=:9000 \ + -e BACKUP_S3_USE_SSL=false \ + -e CLUSTER_HOSTNAME=weaviate-demo \ + semitechnologies/weaviate:1.31.0 +``` + +:::note[Format du point de terminaison et identifiants] + +`BACKUP_S3_ENDPOINT` prend hôte et port sans schéma — le client AWS SDK Go v1 derrière le module rejette toute valeur `http://...` avec `Endpoint url cannot have fully qualified paths`. Le TLS est contrôlé par `BACKUP_S3_USE_SSL=false`, et les requêtes sont en path-style. Passer `BACKUP_S3_ACCESS_KEY_ID` au lieu de `AWS_ACCESS_KEY_ID` laisse le client anonyme, et chaque appel de sauvegarde échoue avec `Access Denied`. + +::: + +Confirmez que le module est actif : + +```bash +curl -s http://localhost:8080/v1/meta | grep -o "backup-s3" +``` + +## 2. Créer une collection et la sauvegarder + +Dans Weaviate 1.31, le schéma se crée par `POST /v1/schema`. Insérez deux objets, puis lancez la sauvegarde : + +```bash +curl -s -X POST http://localhost:8080/v1/schema \ + -H "Content-Type: application/json" \ + -d '{"class":"Doc","vectorizer":"none","properties":[{"name":"title","dataType":["text"]}]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"RustFS vector backup"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"Weaviate on object storage"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/backups/s3 -H "Content-Type: application/json" \ + -d '{"id":"rustfs-demo"}' +``` + +```json +{"backend":"s3","classes":["Doc"],"id":"rustfs-demo","path":"s3://my-bucket/rustfs-demo","status":"STARTED"} +``` + +Attendez `SUCCESS`, puis confirmez les objets dans RustFS, en remplaçant toutes les valeurs de connexion indicatives : + +```bash +curl -s http://localhost:8080/v1/backups/s3/rustfs-demo +aws s3 ls s3://my-bucket/rustfs-demo/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:46:10 304 rustfs-demo/backup_config.json +2026-11-01 13:46:08 1406 rustfs-demo/weaviate-demo/Doc/chunk-1 +2026-11-01 13:46:08 27666 rustfs-demo/weaviate-demo/backup.json +``` + +![Objets de sauvegarde Weaviate dans la console RustFS](./images/rustfs-weaviate-backup.png) + +## 3. Restaurer + +Restaurez la sauvegarde dans Weaviate (supprimez d'abord la classe en ligne pour une restauration propre) : + +```bash +curl -s -X POST http://localhost:8080/v1/backups/s3/rustfs-demo/restore \ + -H "Content-Type: application/json" -d '{}' +``` + +Interrogez les données restaurées : + +```bash +curl -s -X POST http://localhost:8080/v1/graphql -H "Content-Type: application/json" \ + -d '{"query":"{Get{Doc(limit:2){title}}}"}' +``` + +```json +{"data":{"Get":{"Doc":[{"title":"RustFS vector backup"},{"title":"Weaviate on object storage"}]}}} +``` + +## 4. Arrêter ou réinitialiser + +Pour démonter la démo tout en conservant les objets du bucket : + +```bash +docker rm -f weaviate +``` + +Pour supprimer la sauvegarde stockée : + +```bash +aws s3 rm s3://my-bucket/rustfs-demo --recursive \ + --endpoint-url http://:9000 +``` + +## Dépannage + +### `Endpoint url cannot have fully qualified paths` au démarrage + +`BACKUP_S3_ENDPOINT` contient un schéma. Utilisez la forme `hôte:port` nue et réglez `BACKUP_S3_USE_SSL=false`. + +### `Access Denied` à la création d'une sauvegarde + +Le module n'a trouvé aucun identifiant. Dans Weaviate 1.31, le client S3 lit `AWS_ACCESS_KEY_ID` et `AWS_SECRET_ACCESS_KEY` (ou `AWS_ACCESS_KEY`/`AWS_SECRET_KEY`) dans l'environnement — la seule variable `BACKUP_S3_ACCESS_KEY_ID` ne suffit pas. + +### `s3://my-bucket/s3Path/...` apparaît dans l'erreur + +Dans cette version, `BACKUP_S3_PATH` est un sous-préfixe de bucket, pas un commutateur path-style — ne le réglez pas sur `s3Path`. Le client S3 de Weaviate utilise automatiquement le path-style pour les points de terminaison personnalisés. + +### `check if backup ... exists` échoue avec une erreur inattendue + +RustFS est injoignable depuis le conteneur. Vérifiez que l'hôte du point de terminaison se résout et que le bucket existe. + +## Prochaines étapes + +- Consultez les [notes de compatibilité S3](/administration/protocols/s3) avant d'automatiser les planifications de sauvegarde. +- Créez des identifiants de production dédiés avec la [gestion des clés d'accès](/security-compliance/iam/access-token). +- Suivez la [documentation des sauvegardes Weaviate](https://docs.weaviate.io/deploy/configuration/backups) pour les filtres de restauration, les sauvegardes par rôle et l'alternative système de fichiers sur le même bucket. diff --git a/content/ja/developer/integration/ai/cocoindex.md b/content/ja/developer/integration/ai/cocoindex.md new file mode 100644 index 000000000..1eb443975 --- /dev/null +++ b/content/ja/developer/integration/ai/cocoindex.md @@ -0,0 +1,237 @@ +--- +title: "CocoIndex" +description: "RustFS バケットに保存した文書を CocoIndex で埋め込みにインデックスする。" +--- + +このガイドは、AI パイプライン向けの増分インデックスエンジン [CocoIndex](https://github.com/cocoindex-io/cocoindex) を、ドキュメントソースとして **RustFS** に接続します。バケットのプレフィックスから markdown ファイルを一覧し、チャンク化して埋め込みを生成し、Postgres に保存してインデックスをクエリするフローを構築します。このワークフローは CocoIndex `1.0.26` がカスタム S3 エンドポイント経由で RustFS バケットから読み取る形で検証しました。 + +Python 3.11 以上と、フローのターゲットおよび状態のための `pgvector` 拡張付き Postgres が必要です。 + +## アーキテクチャ + +```mermaid +flowchart LR + RustFS["RustFS :9000"] -->|"S3 source: *.md"| Flow["CocoIndex flow"] + Flow -->|"chunks + embeddings"| PG["Postgres + pgvector"] + Query["semantic query"] --> PG +``` + +CocoIndex は自分で作成する aiobotocore クライアント経由でソースオブジェクトを読むため、S3 互換エンドポイントなら何でも使えます。パススタイルアドレッシングの RustFS も例外ではありません。増分更新は内容が変わったファイルだけを再処理し、安定した S3 パスをキーにします。 + +## 1. 環境を準備する + +S3 コネクタ付きの CocoIndex と埋め込みスタックをインストールします: + +```bash +python3 -m venv .venv +./.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu +./.venv/bin/pip install "cocoindex[amazon_s3]" asyncpg pgvector numpy python-dotenv sentence-transformers +``` + +ソース文書をバケットのプレフィックスへアップロードします。接続プレースホルダーをすべて置き換えてください: + +```bash +aws s3 cp ./docs s3://my-bucket/cocoindex-docs/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +upload: docs/rag-basics.md to s3://my-bucket/cocoindex-docs/rag-basics.md +upload: docs/rustfs-overview.md to s3://my-bucket/cocoindex-docs/rustfs-overview.md +``` + +## 2. フローを書く + +環境ファイルとフローを作成します。S3 クライアントは `AWS_ENDPOINT_URL` を設定した状態で作成し、aiobotocore は S3 互換エンドポイントとしてこれを扱います: + +```ini title=".env" +S3_BUCKET=my-bucket +S3_PREFIX=cocoindex-docs/ +AWS_ENDPOINT_URL=http://:9000 +AWS_ACCESS_KEY_ID= +AWS_SECRET_ACCESS_KEY= +AWS_DEFAULT_REGION=us-east-1 +COCOINDEX_DB=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +POSTGRES_URL=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +``` + +```python title="main.py" +import asyncio, os, sys +from dataclasses import dataclass +from typing import AsyncIterator, Annotated + +import aiobotocore.session +import asyncpg +from dotenv import load_dotenv +from numpy.typing import NDArray +from pgvector.asyncpg import register_vector + +load_dotenv() + +import cocoindex as coco +from cocoindex.connectors import amazon_s3, postgres +from cocoindex.ops.sentence_transformers import SentenceTransformerEmbedder +from cocoindex.ops.text import RecursiveSplitter +from cocoindex.resources.chunk import Chunk +from cocoindex.resources.file import PatternFilePathMatcher + +DATABASE_URL = os.environ["POSTGRES_URL"] +TABLE_NAME = "rustfs_doc_embeddings" +PG_SCHEMA_NAME = "coco_examples" +S3_BUCKET = os.environ["S3_BUCKET"] +S3_PREFIX = os.getenv("S3_PREFIX", "") +EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2" +PG_DB = coco.ContextKey[asyncpg.Pool]("db") +S3_CLIENT = coco.ContextKey[object]("s3_client") +EMBEDDER = coco.ContextKey[SentenceTransformerEmbedder]("embedder", detect_change=True) + +_splitter = RecursiveSplitter() + +@coco.lifespan +async def coco_lifespan(builder: coco.EnvironmentBuilder) -> AsyncIterator[None]: + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + builder.provide(PG_DB, pool) + builder.provide(EMBEDDER, SentenceTransformerEmbedder(EMBED_MODEL)) + session = aiobotocore.session.get_session() + async with session.create_client("s3") as s3_client: + builder.provide(S3_CLIENT, s3_client) + yield + +@dataclass +class DocEmbedding: + id: int + filename: str + text: str + embedding: Annotated[NDArray, EMBEDDER] + +@coco.fn +async def process_chunk(chunk: Chunk, filename: str, table: postgres.TableTarget[DocEmbedding]) -> None: + table.declare_row(row=DocEmbedding( + id=abs(hash(f"{filename}:{chunk.start.char_offset}")) % (10 ** 9), + filename=filename, text=chunk.text, + embedding=await coco.use_context(EMBEDDER).embed(chunk.text), + )) + +@coco.fn(memo=True) +async def process_file(file: amazon_s3.S3File, table: postgres.TableTarget[DocEmbedding]) -> None: + text = await file.read_text() + chunks = _splitter.split(text, chunk_size=2000, chunk_overlap=500, language="markdown") + await coco.map(process_chunk, chunks, file.file_path.path.as_posix(), table) + +@coco.fn +async def app_main() -> None: + target_table = await postgres.mount_table_target( + PG_DB, table_name=TABLE_NAME, + table_schema=await postgres.TableSchema.from_class(DocEmbedding, primary_key=["id"]), + pg_schema_name=PG_SCHEMA_NAME, + ) + client = coco.use_context(S3_CLIENT) + files = amazon_s3.list_objects(client, S3_BUCKET, prefix=S3_PREFIX, + path_matcher=PatternFilePathMatcher(included_patterns=["**/*.md"])) + await coco.mount_each(process_file, files.items(), target_table) + +app = coco.App(coco.AppConfig(name="RustFSDocs"), app_main) + +TOP_K = 5 + + +async def query_once( + pool: asyncpg.Pool, + embedder: SentenceTransformerEmbedder, + query: str, + *, + top_k: int = TOP_K, +) -> None: + query_vec = await embedder.embed(query) + async with pool.acquire() as conn: + rows = await conn.fetch( + f""" + SELECT filename, text, embedding <=> $1 AS distance + FROM "{PG_SCHEMA_NAME}"."{TABLE_NAME}" + ORDER BY distance ASC + LIMIT $2 + """, + query_vec, + top_k, + ) + for r in rows: + score = 1.0 - float(r["distance"]) + print(f"[{score:.3f}] {r['filename']}") + print(f" {r['text']}") + print("---") + + +async def query(initial_query: str | None = None) -> None: + embedder = SentenceTransformerEmbedder(EMBED_MODEL) + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + if initial_query is not None: + await query_once(pool, embedder, initial_query) + return + while True: + q = input("Enter search query (or Enter to quit): ").strip() + if not q: + break + await query_once(pool, embedder, q) + + +if __name__ == "__main__": + initial = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else None + asyncio.run(query(initial)) +``` + +## 3. RustFS からインデックスを構築する + +```bash +set -a && . ./.env && set +a +./.venv/bin/cocoindex update main +``` + +```text +✅ app_main: 1 total | 1 added +✅ process_file: 2 total | 2 added +``` + +2 つの markdown ファイルが RustFS バケットから読み込まれ、チャンク化されて Postgres に埋め込まれました。`main.py` のエントリポイントでインデックスを検索します。スクリプトは `.env` を読み込み、同じモデルで質問の埋め込みを計算し、最も近いチャンクを表示します: + +```bash +./.venv/bin/python main.py "what does RustFS expose" +``` + +```text +[0.163] rag-basics.md + Retrieval augmented generation combines a retriever and a generator. +--- +``` + +クエリがヒットするチャンクの正本(source of truth)はバケットです。RustFS 内のファイルを編集して `cocoindex update main` を再実行すれば、変更部分だけが増分で再インデックスされます。 + +![RustFS コンソール上の CocoIndex ソース文書](./images/rustfs-cocoindex-source.png) + +## 4. 停止またはリセット + +インデックス済みの文書を削除するには: + +```bash +aws s3 rm s3://my-bucket/cocoindex-docs --recursive \ + --endpoint-url http://:9000 +``` + +## トラブルシューティング + +### `Environment settings must provide Settings.db_path` + +CocoIndex は自身の状態も Postgres に保持します。`COCOINDEX_DB`(ターゲットには `POSTGRES_URL`)を、`pgvector` 拡張が有効なデータベースに向けてください。 + +### フローからの `InvalidAccessKeyId` や接続タイムアウト + +フロー実行前に環境変数がエクスポートされていません(`set -a && . ./.env && set +a`)。`AWS_ENDPOINT_URL` にはスキーマが必須で、認証情報は標準の `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` のペアで渡します。 + +### フローがファイルを 1 つも見つけられない + +プレフィックスとマッチャーを確認してください。`list_objects` は `S3_PREFIX` を走査し、`included_patterns` で絞り込みます。`aws s3 ls s3://my-bucket/cocoindex-docs/` でオブジェクトの存在を確認してください。 + +## 次のステップ + +- 追加のソースを接続する前に [S3 互換性についての注意](/administration/protocols/s3) を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token) で本番用の専用認証情報を作成してください。 +- [CocoIndex Amazon S3 コネクタのドキュメント](https://cocoindex.io/docs/connectors/amazon_s3) に従い、パスマッチャー・サイズ制限・ライブ更新を活用してください。 diff --git a/content/ja/developer/integration/ai/dify.md b/content/ja/developer/integration/ai/dify.md new file mode 100644 index 000000000..376369a65 --- /dev/null +++ b/content/ja/developer/integration/ai/dify.md @@ -0,0 +1,135 @@ +--- +title: "Dify" +description: "Dify のアップロードファイル・ナレッジベース文書・システム状態を RustFS バケットに保存する。" +--- + +このガイドは、オープンソースの LLM アプリケーションプラットフォーム [Dify](https://github.com/langgenius/dify) を、OpenDAL ストレージバックエンド経由で **RustFS** に接続します。ファイルストレージをローカルディスクから RustFS バケットに切り替え、スタックを起動し、ナレッジベースにドキュメントをアップロードして、バケット内のオブジェクトを確認します。このワークフローは Dify `1.18.0`(Docker Compose)で検証しました。 + +Docker Compose が必要です。このデプロイはローカルでの統合テスト用であり、本番環境向けではありません。 + +## アーキテクチャ + +```mermaid +flowchart LR + Console["Console / API"] -->|"files/upload"| RustFS["RustFS :9000"] + RustFS -->|"upload_files, secrets"| API["api / worker"] +``` + +Dify は、アップロードされた文書・ナレッジベースのファイル・ブートストラップシークレット(`.dify_secret_key`、ワークスペース鍵)を、設定されたストレージバックエンド経由で永続化します。バックエンドがバケットなら、これらはコンテナのディスクには残りません。 + +## 1. RustFS 向けにストレージを設定する + +`docker/.env`(`.env.example` からコピー)で OpenDAL を S3 スキームに切り替えます: + +```ini title="docker/.env" +STORAGE_TYPE=opendal +OPENDAL_SCHEME=s3 +OPENDAL_S3_ENDPOINT=http://:9000 +OPENDAL_S3_BUCKET=dify +OPENDAL_S3_ACCESS_KEY_ID= +OPENDAL_S3_SECRET_ACCESS_KEY= +OPENDAL_S3_REGION=us-east-1 +OPENDAL_S3_ENABLE_PATH_STYLE=true +OPENDAL_S3_ROOT=/ +``` + +スタック起動前にバケットを作成します: + +```bash +aws s3 mb s3://dify --endpoint-url http://:9000 +``` + +:::note[RustFS を Compose ネットワークに接続する] + +Compose スタックは独自のブリッジネットワークで動き、Docker はブリッジ同士を分離します。`http://172.17.0.2:9000` のようなエンドポイントは `api` コンテナからタイムアウトします。RustFS コンテナをエイリアス付きで Compose ネットワークに接続し、エンドポイントのホストにはエイリアスを使ってください: + +```bash +docker network connect --alias rustfs +``` + +`.env` を変更した後はスタックを再作成してください。`docker compose restart` は古い環境変数を使い続けます。 + +::: + +## 2. スタックを起動して初期化する + +```bash +cd dify/docker +docker compose up -d +``` + +`api` のヘルスチェックが通るのを待ち、Web UI(`http://localhost:80`)で管理者アカウントを作成します。Dify は直ちにブートストラップ状態をバケットへ書き込みます: + +```bash +aws s3 ls s3://dify/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 14:31:00 65 .dify_secret_key +2026-11-01 14:33:06 1674 privkeys//private.pem +``` + +シークレットキーとワークスペース鍵は RustFS 上にあります。コンテナには残すべき状態がありません。 + +## 3. ナレッジベースに文書をアップロードする + +UI でナレッジベースを作成し、文書をアップロードします。アップロードはバケットの `upload_files//` の下に着地します: + +```bash +aws s3 ls s3://dify/upload_files/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 15:25:53 128 upload_files//0ae369a1-70ed-40e8-b3d9-0f12d0b7c699.txt +``` + +オブジェクトはアップロード完了の瞬間に現れます。インデックス作成はバケット上のコピーに対して実行されます。 + +![RustFS コンソールに保存された Dify のアップロード](./images/rustfs-dify-uploads.png) + +## 4. 停止またはリセット + +バケットのオブジェクトを残したままスタックを解体するには: + +```bash +docker compose down +``` + +Dify のデータを削除するには: + +```bash +aws s3 rm s3://dify --recursive \ + --endpoint-url http://:9000 +``` + +:::warning[リセット時は bind mount も消す] + +Dify の Compose ファイルはデータベースとストレージを `docker/volumes/` 以下にバインドマウントします。`docker compose down -v` はバインドマウントを削除しません。クリーンな状態にするには `docker/volumes/` を明示的に削除してください。そうしないと旧管理者アカウントと暗号化状態が残ります。 + +::: + +## トラブルシューティング + +### 起動ログがバケットに対して `tcp connect error: Connection timed out` を表示する + +スタックから RustFS のアドレスに到達できていません。Docker ブリッジ間のネットワーク分離です。手順 1 のとおり RustFS をエイリアス付きで Compose ネットワークに接続してください。 + +### ログインが `Invalid encrypted data` で失敗する + +管理者のパスワードフィールドはフロントエンドが Base64 エンコードします。console API に平文を送ると失敗します。アカウント操作には Web UI を使うか、フロントエンドと同じ方法でフィールドをエンコードしてください。 + +### 文書作成時に `Default model not found for text-embedding` + +`high-quality` インデックスモードには Dify で設定済みの embedding モデルプロバイダーが必要です。ストレージだけの検証なら `economy` インデックスを使うか、先にモデルプロバイダーを設定してください。 + +### アップロードがローカルディスクに落ち続ける + +`api` と `worker` コンテナが `.env` 変更前の古いインスタンスです。`docker compose up -d --force-recreate` でスタック全体を再作成し、全サービスに新しいストレージ設定を読ませてください。 + +## 次のステップ + +- 大きなナレッジベースを運用する前に [S3 互換性についての注意](/administration/protocols/s3) を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token) で本番用の専用認証情報を作成してください。 +- [Dify 環境変数リファレンス](https://docs.dify.ai/en/self-host/deploy/configuration/environments) に従い、プラグインデーモン固有の S3 設定や同じバケットでのマルチパート調整を活用してください。 diff --git a/content/ja/developer/integration/ai/feast.md b/content/ja/developer/integration/ai/feast.md new file mode 100644 index 000000000..0bc9eeba9 --- /dev/null +++ b/content/ja/developer/integration/ai/feast.md @@ -0,0 +1,164 @@ +--- +title: "Feast" +description: "Feast のフィーチャーレジストリとオフライン Parquet ソースを RustFS バケットに保持する。" +--- + +このガイドは、オープンソースのフィーチャーストア [Feast](https://github.com/feast-dev/feast) を **RustFS** に接続し、2 つのストレージ役割を同時に担わせます。フィーチャーレジストリ(`registry.db`)をバケットに置き、オフラインのフィーチャーソースを同じバケット内の Parquet ファイルにします。フィーチャーリポジトリを適用し、RustFS からフィーチャーをオンラインストアへマテリアライズして読み戻します。このワークフローは Feast `0.67.0` で検証しました。 + +Python 3.10 以上が必要です。このデプロイはローカルでの統合テスト用であり、本番環境向けではありません。 + +## アーキテクチャ + +```mermaid +flowchart LR + Apply["feast apply"] -->|"registry.db"| RustFS["RustFS :9000"] + RustFS -->|"parquet offline read"| Materialize["feast materialize"] + Materialize -->|"features"| Online["SQLite online store"] + Query["get_online_features"] --> Online +``` + +レジストリストアは boto3 でバケット内の `registry.db` を読み書きし、ファイルオフラインストアは s3fs で Parquet を読みます。どちらもカスタムエンドポイントを扱えるため、フィーチャー履歴レイヤー全体がバケット上にあり、オンラインストアだけがローカルに残ります。 + +## 1. S3 サポート付きの Feast をインストールする + +ベースパッケージには S3 クライアントが含まれないため、明示的にインストールします: + +```bash +python3 -m venv .venv +./.venv/bin/pip install feast boto3 s3fs +``` + +オフラインのフィーチャーデータをアップロードします。接続プレースホルダーをすべて置き換えてください: + +```bash +aws s3 cp driver_stats.parquet s3://my-bucket/feast/driver_stats.parquet \ + --endpoint-url http://:9000 +``` + +## 2. リポジトリを設定する + +リポジトリのファイルを作成します。レジストリは素の `s3://` URI で、エンドポイントの上書きは環境変数 `FEAST_S3_ENDPOINT_URL` から取得します。データソースは自身の `s3_endpoint_override` を持ちます: + +```yaml title="feature_store.yaml" +project: rustfs_demo +provider: local +registry: s3://my-bucket/feast/registry.db +offline_store: + type: file +entity_key_serialization_version: 3 +``` + +```python title="features.py" +from datetime import timedelta +from feast import Entity, FeatureView, Field, FileSource +from feast.types import Float32, Int64 + +driver = Entity(name="driver", join_keys=["driver_id"]) +source = FileSource( + name="driver_stats_source", + path="s3://my-bucket/feast/driver_stats.parquet", + timestamp_field="event_timestamp", + s3_endpoint_override="http://:9000", +) +driver_stats = FeatureView( + name="driver_stats", + entities=[driver], + ttl=timedelta(days=1), + schema=[Field(name="conv_rate", dtype=Float32), Field(name="avg_daily_trips", dtype=Int64)], + source=source, +) +``` + +レジストリクライアントのためにエンドポイントと認証情報をエクスポートします: + +```bash +export FEAST_S3_ENDPOINT_URL=http://:9000 +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export AWS_DEFAULT_REGION=us-east-1 +``` + +## 3. リポジトリを適用してマテリアライズする + +`feast apply` が `registry.db` をバケットへ書き込み、`materialize-incremental` が RustFS の Parquet フィーチャーをローカルのオンラインストアへ読み込みます: + +```bash +./.venv/bin/feast apply +./.venv/bin/feast materialize-incremental 2026-11-02T00:00:00Z +``` + +```text +Created entity driver +Created feature view driver_stats +... +driver_stats from 2026-10-31 ... to 2026-11-02 00:00:00+00:00: +``` + +レジストリのオブジェクトが RustFS にあることを確認します: + +```bash +aws s3 ls s3://my-bucket/feast/ \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:57:58 1322 registry.db +2026-11-01 13:56:43 3680 driver_stats.parquet +``` + +![RustFS コンソール上の Feast レジストリとフィーチャーデータ](./images/rustfs-feast-registry.png) + +## 4. フィーチャーを読み戻す + +```bash +./.venv/bin/python - <<'PY' +from feast import FeatureStore +store = FeatureStore(repo_path=".") +res = store.get_online_features( + features=["driver_stats:conv_rate", "driver_stats:avg_daily_trips"], + entity_rows=[{"driver_id": 101}], +).to_dict() +print("conv_rate:", res["conv_rate"][0]) +print("avg_daily_trips:", res["avg_daily_trips"][0]) +PY +``` + +```text +conv_rate: 0.699999988079071 +avg_daily_trips: 130 +``` + +提供されたフィーチャーは、RustFS が保存する Parquet ファイルからマテリアライズされたものです。 + +## 5. 停止またはリセット + +リポジトリのオブジェクトを削除するには: + +```bash +aws s3 rm s3://my-bucket/feast --recursive \ + --endpoint-url http://:9000 +``` + +## トラブルシューティング + +### `Could not import module 'feast.infra.registry.s3'` + +S3 レジストリストアには `boto3` が必要で、Feast のベースパッケージには含まれません。手順 1 のとおり `pip install boto3`(オフラインストアには `s3fs` も)で解決します。 + +### マテリアライズ時に `Install s3fs to access S3` + +ファイルオフラインストアは `s3fs` 経由で Parquet を読みます。`boto3` とともにインストールしてください。 + +### レジストリの S3 ストアがエンドポイントを無視する + +レジストリはエンドポイントを環境変数 `FEAST_S3_ENDPOINT_URL` からのみ読みます。素の `AWS_ENDPOINT_URL` はそこでは扱われません。`FileSource` は自身の `s3_endpoint_override` を持ちます。両方の設定が必要です。 + +### エンティティキー シリアライゼーションの非推奨警告 + +`feature_store.yaml` で `entity_key_serialization_version: 3` を設定してください。3 未満のバージョンは新しいオンラインストアでは受け付けられません。 + +## 次のステップ + +- 本番のレジストリをバケットに向ける前に [S3 互換性についての注意](/administration/protocols/s3) を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token) で本番用の専用認証情報を作成してください。 +- [Feast ドキュメント](https://docs.feast.dev/) に従い、同じバケットでストリーミングソース・フィーチャーサービング・レジストリ代替を活用してください。 diff --git a/content/ja/developer/integration/ai/images/rustfs-cocoindex-source.png b/content/ja/developer/integration/ai/images/rustfs-cocoindex-source.png new file mode 100644 index 000000000..61de59293 Binary files /dev/null and b/content/ja/developer/integration/ai/images/rustfs-cocoindex-source.png differ diff --git a/content/ja/developer/integration/ai/images/rustfs-dify-uploads.png b/content/ja/developer/integration/ai/images/rustfs-dify-uploads.png new file mode 100644 index 000000000..3e4cec9ba Binary files /dev/null and b/content/ja/developer/integration/ai/images/rustfs-dify-uploads.png differ diff --git a/content/ja/developer/integration/ai/images/rustfs-feast-registry.png b/content/ja/developer/integration/ai/images/rustfs-feast-registry.png new file mode 100644 index 000000000..bceea1328 Binary files /dev/null and b/content/ja/developer/integration/ai/images/rustfs-feast-registry.png differ diff --git a/content/ja/developer/integration/ai/images/rustfs-ragflow-docs.png b/content/ja/developer/integration/ai/images/rustfs-ragflow-docs.png new file mode 100644 index 000000000..7ca2e55ee Binary files /dev/null and b/content/ja/developer/integration/ai/images/rustfs-ragflow-docs.png differ diff --git a/content/ja/developer/integration/ai/meta.json b/content/ja/developer/integration/ai/meta.json index f03ec4897..4deb8701f 100644 --- a/content/ja/developer/integration/ai/meta.json +++ b/content/ja/developer/integration/ai/meta.json @@ -4,6 +4,10 @@ "mlflow", "ray", "sglang", - "vllm" + "vllm", + "dify", + "ragflow", + "cocoindex", + "feast" ] } diff --git a/content/ja/developer/integration/ai/ragflow.md b/content/ja/developer/integration/ai/ragflow.md new file mode 100644 index 000000000..ef5ba2bb3 --- /dev/null +++ b/content/ja/developer/integration/ai/ragflow.md @@ -0,0 +1,144 @@ +--- +title: "RAGFlow" +description: "RAGFlow のアップロード文書とワークスペース状態を RustFS バケットに保存する。" +--- + +このガイドは、オープンソースの RAG エンジン [RAGFlow](https://github.com/infiniflow/ragflow) を、オブジェクトストレージとして **RustFS** に接続します。RAGFlow は MinIO 互換のクライアント設定を通じて、アップロードされたすべてのドキュメントと解析成果物を S3 互換ストレージに保存します。その設定を RustFS に向け、スタックを起動し、ナレッジベースにドキュメントをアップロードして、バケット内のオブジェクトを確認します。このワークフローは `infiniflow/ragflow:v1.0.0-rc3` と Infinity ドキュメントエンジンで検証しました。 + +Docker Compose が必要です。このデプロイはローカルでの統合テスト用であり、本番環境向けではありません。 + +## アーキテクチャ + +```mermaid +flowchart LR + Upload["Knowledge base upload"] --> API["RAGFlow API :9380"] + API -->|"documents"| RustFS["RustFS :9000"] + API --> Doc["Infinity / Elasticsearch"] +``` + +テナントごとにテナント ID を名前とするバケットが割り当てられ、アップロードされた各ファイルはそのバケット内のオブジェクトになります。解析はソース文書の隣に成果物を書き込みます。 + +## 1. スタックを RustFS 向けに設定する + +RAGFlow をクローンし、`docker/.env` を編集します。Infinity ドキュメントエンジンを選び、ストレージクライアントを RustFS に向けます: + +```ini title="docker/.env" +DOC_ENGINE=infinity +MINIO_HOST= +MINIO_USER= +MINIO_PASSWORD= +``` + +`docker/service_conf.yaml.template` の `minio:` セクションはこれらの変数から生成されるため、同じフィールドで任意の S3 互換エンドポイントを扱えます。RAGFlow は最初のアップロード時にテナントごとのバケットを自動作成するため、事前作成は不要です。 + +:::note[RustFS コンテナにネットワークエイリアスを付ける] + +Compose スタックは独自のブリッジネットワークで動き、Docker はブリッジ同士を分離するため、RustFS コンテナの `172.17.0.x` アドレスはスタックから到達できません。RustFS をエイリアス付きで Compose ネットワークに接続し、そのエイリアスを `MINIO_HOST` に使ってください: + +```bash +docker network connect --alias rustfs ragflow_ragflow +``` + +レジストリの都合で内蔵 MinIO イメージ(quay.io から)を取得できない場合は置き換えてください。`MINIO_HOST` が別の場所を指していれば、スタックはそれにアクセスしません。 + +::: + +## 2. スタックを起動する + +```bash +cd ragflow/docker +docker compose -p ragflow up -d +``` + +API の起動を待ち、サーバーが読み込んだストレージ設定を確認します: + +```bash +docker logs ragflow-cpu 2>&1 | grep "minio:" +``` + +```text +minio: {'user': '...', 'password': '...', 'host': 'rustfs:9000', 'bucket': '', 'prefix_path': ''} +``` + +`bucket` が空なのは想定通りです。RAGFlow は最初のアップロード時にテナントごとのバケットを作成します。 + +## 3. ナレッジベースにドキュメントをアップロードする + +ユーザーと API キーを作成し(`https://localhost:443` の Web UI またはユーザー API 経由)、HTTP API を使います: + +```bash +curl -s -X POST http://localhost:9380/api/v1/datasets \ + -H "Authorization: Bearer " -H "Content-Type: application/json" \ + -d '{"name":"rustfs-kb"}' + +curl -s -X POST "http://localhost:9380/api/v1/datasets//documents" \ + -H "Authorization: Bearer " \ + -F "file=@rustfs-overview.txt" +``` + +```json +{"code":0,"data":[{"chunk_method":"naive","location":"rustfs-overview.txt","name":"rustfs-overview.txt","run":"UNSTART"}]} +``` + +オブジェクトが RustFS に着いたことを確認します。テナントバケットはテナント ID を名前とします: + +```bash +aws s3 ls s3:/// --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 16:02:41 204 rg-doc.txt +``` + +オブジェクトを読み戻し、アップロードしたファイルと比較します: + +```bash +aws s3 cp s3:///rg-doc.txt - \ + --endpoint-url http://:9000 +``` + +![RustFS コンソール上の RAGFlow アップロード文書](./images/rustfs-ragflow-docs.png) + +## 4. 解析と検索 + +ドキュメント解析(`{"run":"parse"}` を付けた `PUT /api/v1/datasets/{id}/documents/{doc_id}`)は、RustFS に保存されたオブジェクトを消費し、チャンクの成果物をその隣に書き込みます。解析にはさらに RAGFlow で設定した embedding モデルが必要です。このステップはモデル構成に依存するもので、ストレージには依存しません。 + +## 5. 停止またはリセット + +バケットのオブジェクトを残したままスタックを停止するには: + +```bash +docker compose -p ragflow stop +``` + +テナントのデータを削除するには: + +```bash +aws s3 rm s3:// --recursive \ + --endpoint-url http://:9000 +``` + +## トラブルシューティング + +### アップロードは成功するが RustFS に何も現れない + +サーバーがまだ内蔵 MinIO と通信しています。起動ログの `minio:` 行を確認し、ホストが RustFS のエイリアスでなければ、`.env` の変更がコンテナに届いていません。`docker compose -p ragflow up -d --force-recreate ragflow-cpu` で再作成してください。 + +### 起動ログに `tcp connect error: Connection timed out` + +RustFS コンテナのアドレスが Compose ネットワークから到達可能ではありません。手順 1 のとおり RustFS をエイリアス付きで Compose ネットワークに接続し、`MINIO_HOST` にはエイリアスを指定してください。 + +### `/api/v1` で `Authentication error: API key is invalid!` + +`/api/v1` の SDK ルートは RAGFlow の API キー(Web UI で作成)を受け付け、ログインのアクセストークンは受け付けません。`/v1/*` ルートはログインセッションを使います。 + +### 登録やログインでパスワードエラー + +RAGFlow は API に到達する前に、同梱の RSA 公開鍵でパスワードを暗号化することを求めます。Web UI はこれを自動で行います。クライアント側の暗号化を再現しない限り、アカウント作成には UI を使用してください。 + +## 次のステップ + +- 大規模な取り込みの前に [S3 互換性についての注意](/administration/protocols/s3) を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token) で本番用の専用認証情報を作成してください。 +- [RAGFlow ドキュメント](https://ragflow.io/docs/dev/) に従い、同じバケットでチャンクテンプレート・embedding モデル・エージェントワークフローを活用してください。 diff --git a/content/ja/developer/integration/database/images/rustfs-qdrant-snapshots.png b/content/ja/developer/integration/database/images/rustfs-qdrant-snapshots.png new file mode 100644 index 000000000..de4d1fbfd Binary files /dev/null and b/content/ja/developer/integration/database/images/rustfs-qdrant-snapshots.png differ diff --git a/content/ja/developer/integration/database/images/rustfs-weaviate-backup.png b/content/ja/developer/integration/database/images/rustfs-weaviate-backup.png new file mode 100644 index 000000000..08d28fdcc Binary files /dev/null and b/content/ja/developer/integration/database/images/rustfs-weaviate-backup.png differ diff --git a/content/ja/developer/integration/database/meta.json b/content/ja/developer/integration/database/meta.json index 9eccfd10e..3caae5439 100644 --- a/content/ja/developer/integration/database/meta.json +++ b/content/ja/developer/integration/database/meta.json @@ -9,6 +9,8 @@ "lancedb", "milvus", "trino", - "vitess" + "vitess", + "qdrant", + "weaviate" ] } diff --git a/content/ja/developer/integration/database/qdrant.md b/content/ja/developer/integration/database/qdrant.md new file mode 100644 index 000000000..22d477597 --- /dev/null +++ b/content/ja/developer/integration/database/qdrant.md @@ -0,0 +1,133 @@ +--- +title: "Qdrant" +description: "S3 バックエンドのスナップショットストレージで Qdrant コレクションスナップショットを RustFS バケットに保存する。" +--- + +このガイドは、AI 検索と RAG 向けのオープンソース ベクトルデータベース [Qdrant](https://github.com/qdrant/qdrant) を、スナップショットの保存先として **RustFS** に接続します。S3 バックエンドのスナップショットを有効化し、ベクトル入りコレクションを作成し、スナップショットをバケットへアップロードした後、まっさらなノードにリストアします。このワークフローは `qdrant/qdrant:v1.20.0` がパススタイルアドレッシングで RustFS バケットへスナップショットを書き込む形で検証しました。 + +Docker が必要です。このデプロイはローカルでの統合テスト用であり、本番環境向けではありません。 + +## アーキテクチャ + +```mermaid +flowchart LR + API["Qdrant REST :6333"] -->|"snapshot"| S3["RustFS :9000"] + S3 -->|"recover"| Fresh["Fresh Qdrant node"] +``` + +`snapshots_storage: s3` を有効にすると、各コレクションスナップショットは `/snapshots//` の下にバケットへアップロードされます。同じバケットを指す新しいノードは、ローカルファイルなしで任意のコレクションを再構築できます。 + +## 1. Qdrant を RustFS に向ける + +スナップショットストレージは環境変数で設定します。`QDRANT__` プレフィックスが設定ツリーに対応し、`S3_CONFIG__ENDPOINT_URL` が MinIO 類のストレージ向けカスタムエンドポイントのフィールドです。バケットは事前に作成してください。プレフィックスは空でも構いません。 + +```bash +docker run -d --name qdrant -p 6333:6333 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__SNAPSHOTS_STORAGE=s3 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__BUCKET=my-bucket \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__PREFIX=qdrant \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__REGION=us-east-1 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ACCESS_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__SECRET_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ENDPOINT_URL=http://:9000 \ + qdrant/qdrant:v1.20.0 +``` + +:::note[QDRANT__STORAGE__SNAPSHOTS_CONFIG のパスを使う] + +リリース済みの Qdrant では設定は `storage.snapshots_config` の下にあり(`storage.snapshots` ではない)、S3 セクションのエンドポイントキーは `endpoint_url` です。古いキー名の `custom_config.yaml` をマウントしても黙って無視され、スナップショットはローカルの `./snapshots` に書き込まれ続けます。切り替わりの確認は、スナップショット作成後にローカルディレクトリが空のままであることで行います。 + +::: + +## 2. コレクションを作成してスナップショットを取る + +コレクションを作成し、ポイントを挿入し、スナップショットを要求します: + +```bash +curl -s -X PUT http://localhost:6333/collections/demo \ + -H "Content-Type: application/json" \ + -d '{"vectors":{"size":4,"distance":"Dot"}}' + +curl -s -X PUT "http://localhost:6333/collections/demo/points?wait=true" \ + -H "Content-Type: application/json" \ + -d '{"points":[{"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"city":"Berlin"}},{"id":2,"vector":[0.9,0.8,0.7,0.6],"payload":{"city":"Tokyo"}}]}' + +curl -s -X POST http://localhost:6333/collections/demo/snapshots +``` + +```json +{"result":{"name":"demo-8437507706552082-2026-11-01-13-31-15-0.snapshot","size":64512},"status":"ok"} +``` + +スナップショットのオブジェクトが RustFS に着いたことを確認します。接続プレースホルダーをすべて置き換えてください: + +```bash +aws s3 ls s3://my-bucket/qdrant/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:31:15 64512 qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot +``` + +![RustFS コンソール上の Qdrant スナップショットのオブジェクト](./images/rustfs-qdrant-snapshots.png) + +## 3. まっさらなノードでリストアする + +スナップショットは同名のコレクションへリストアされます。同じバケットを指すようにローカルノードを初期化(または 2 台目を起動)し、RustFS からスナップショットをダウンロードしてリカバリ API に渡します: + +```bash +aws s3 cp "s3://my-bucket/qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" . \ + --endpoint-url http://:9000 + +curl -s -X POST "http://localhost:6333/collections/demo/snapshots/upload?priority=snapshot" \ + -F "snapshot=@demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" +``` + +リストアされたデータを確認します: + +```bash +curl -s -X POST http://localhost:6333/collections/demo/points/scroll \ + -H "Content-Type: application/json" -d '{"limit":2,"with_payload":true}' +``` + +```json +{"result":{"points":[{"id":1,"payload":{"city":"Berlin"}},{"id":2,"payload":{"city":"Tokyo"}}]},"status":"ok"} +``` + +ベクトルも payload も、RustFS が保存したスナップショットから完全に戻ってきます。 + +## 4. 停止またはリセット + +バケットのオブジェクトを残したままデモを解体するには: + +```bash +docker rm -f qdrant +``` + +保存済みスナップショットを削除するには: + +```bash +aws s3 rm s3://my-bucket/qdrant --recursive \ + --endpoint-url http://:9000 +``` + +## トラブルシューティング + +### スナップショットがコンテナの `/qdrant/snapshots` に現れ続ける + +ストレージの切り替えが適用されていません。変数のパスが違うか、古い設定ファイルが上書きしています。手順 1 の `QDRANT__STORAGE__SNAPSHOTS_CONFIG__*` 変数を正確に使ってコンテナを再起動し、その後ローカルのスナップショットディレクトリが空のままであることを確認してください。 + +### `Wrong input: Snapshot is not compatible with existing collection` + +復元先のコレクションが別スキーマで既に存在します。リストア前に空または古いコレクションを削除してください。アップロード API がスナップショットからコレクションを作成します。 + +### スナップショット作成後にバケットが空 + +バケット名かエンドポイントが誤りです。エンドポイントにはスキーマが必須で、バケットは存在している必要があります。オブジェクトキーは `/snapshots//.snapshot` なので、再帰的に一覧してください。 + +## 次のステップ + +- スナップショットバックアップを計画する前に [S3 互換性についての注意](/administration/protocols/s3) を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token) で本番用の専用認証情報を作成してください。 +- [Qdrant スナップショットのドキュメント](https://qdrant.tech/documentation/snapshots/) に従い、同じバケットでフルストレージスナップショット・シャード単位のスナップショット・バージョン互換性を活用してください。 diff --git a/content/ja/developer/integration/database/weaviate.md b/content/ja/developer/integration/database/weaviate.md new file mode 100644 index 000000000..25ac33506 --- /dev/null +++ b/content/ja/developer/integration/database/weaviate.md @@ -0,0 +1,148 @@ +--- +title: "Weaviate" +description: "backup-s3 モジュールで Weaviate コレクションを RustFS バケットへバックアップする。" +--- + +このガイドは、AI 検索と RAG 向けのオープンソース ベクトルデータベース [Weaviate](https://github.com/weaviate/weaviate) を、`backup-s3` モジュール経由で **RustFS** に接続します。モジュールを有効化し、ベクトル入りコレクションを作成し、バケット内にバックアップを作成した後、リストアします。このワークフローは `semitechnologies/weaviate:1.31.0` が RustFS バケットへバックアップする形で検証しました。 + +Docker が必要です。このデプロイはローカルでの統合テスト用であり、本番環境向けではありません。 + +## アーキテクチャ + +```mermaid +flowchart LR + Weaviate["Weaviate :8080"] -->|"backup create"| RustFS["RustFS :9000"] + RustFS -->|"backup restore"| Weaviate +``` + +バックアップは `backup_config.json`、クラスごとの `backup.json`、データチャンクをバケットの `/` プレフィックスへ書き込みます。リストアは同じコレクション名で読み戻します。 + +## 1. backup-s3 モジュールを有効にする + +モジュールと S3 設定付きで Weaviate を起動します。認証情報は標準の AWS 変数で渡します。Weaviate 1.31 のモジュールは `BACKUP_S3_ACCESS_KEY_ID` ではなく `AWS_ACCESS_KEY_ID` と `AWS_SECRET_ACCESS_KEY` を読みます: + +```bash +docker run -d --name weaviate -p 8080:8080 \ + -e QUERY_DEFAULTS_LIMIT=20 \ + -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \ + -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \ + -e ENABLE_MODULES=backup-s3 \ + -e BACKUP_S3_BUCKET=my-bucket \ + -e AWS_REGION=us-east-1 \ + -e AWS_ACCESS_KEY_ID= \ + -e AWS_SECRET_ACCESS_KEY= \ + -e BACKUP_S3_ENDPOINT=:9000 \ + -e BACKUP_S3_USE_SSL=false \ + -e CLUSTER_HOSTNAME=weaviate-demo \ + semitechnologies/weaviate:1.31.0 +``` + +:::note[エンドポイント形式と認証情報] + +`BACKUP_S3_ENDPOINT` はスキーマなしの `host:port` を受け付けます。モジュールの背後にある AWS SDK Go v1 クライアントは `http://...` 形式を `Endpoint url cannot have fully qualified paths` で拒否します。TLS は `BACKUP_S3_USE_SSL=false` で制御し、リクエストはパススタイルです。`AWS_ACCESS_KEY_ID` の代わりに `BACKUP_S3_ACCESS_KEY_ID` を渡すとクライアントは匿名になり、すべてのバックアップ呼び出しが `Access Denied` で失敗します。 + +::: + +モジュールが有効になったことを確認します: + +```bash +curl -s http://localhost:8080/v1/meta | grep -o "backup-s3" +``` + +## 2. コレクションを作成してバックアップする + +Weaviate 1.31 では `POST /v1/schema` でスキーマを作成します。オブジェクトを 2 つ挿入してからバックアップを開始します: + +```bash +curl -s -X POST http://localhost:8080/v1/schema \ + -H "Content-Type: application/json" \ + -d '{"class":"Doc","vectorizer":"none","properties":[{"name":"title","dataType":["text"]}]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"RustFS vector backup"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"Weaviate on object storage"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/backups/s3 -H "Content-Type: application/json" \ + -d '{"id":"rustfs-demo"}' +``` + +```json +{"backend":"s3","classes":["Doc"],"id":"rustfs-demo","path":"s3://my-bucket/rustfs-demo","status":"STARTED"} +``` + +`SUCCESS` を待ち、RustFS 内のオブジェクトを確認します。接続プレースホルダーをすべて置き換えてください: + +```bash +curl -s http://localhost:8080/v1/backups/s3/rustfs-demo +aws s3 ls s3://my-bucket/rustfs-demo/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:46:10 304 rustfs-demo/backup_config.json +2026-11-01 13:46:08 1406 rustfs-demo/weaviate-demo/Doc/chunk-1 +2026-11-01 13:46:08 27666 rustfs-demo/weaviate-demo/backup.json +``` + +![RustFS コンソール上の Weaviate バックアップのオブジェクト](./images/rustfs-weaviate-backup.png) + +## 3. リストアする + +バックアップを Weaviate へリストアします(クリーンな復元のため、先にライブのクラスを削除します): + +```bash +curl -s -X POST http://localhost:8080/v1/backups/s3/rustfs-demo/restore \ + -H "Content-Type: application/json" -d '{}' +``` + +リストアされたデータをクエリします: + +```bash +curl -s -X POST http://localhost:8080/v1/graphql -H "Content-Type: application/json" \ + -d '{"query":"{Get{Doc(limit:2){title}}}"}' +``` + +```json +{"data":{"Get":{"Doc":[{"title":"RustFS vector backup"},{"title":"Weaviate on object storage"}]}}} +``` + +## 4. 停止またはリセット + +バケットのオブジェクトを残したままデモを解体するには: + +```bash +docker rm -f weaviate +``` + +保存済みバックアップを削除するには: + +```bash +aws s3 rm s3://my-bucket/rustfs-demo --recursive \ + --endpoint-url http://:9000 +``` + +## トラブルシューティング + +### 起動時に `Endpoint url cannot have fully qualified paths` + +`BACKUP_S3_ENDPOINT` にスキーマが含まれています。素の `host:port` 形式にして `BACKUP_S3_USE_SSL=false` を設定してください。 + +### バックアップ作成時に `Access Denied` + +モジュールが認証情報を取得できていません。Weaviate 1.31 の S3 クライアントは環境変数 `AWS_ACCESS_KEY_ID` と `AWS_SECRET_ACCESS_KEY`(または `AWS_ACCESS_KEY`/`AWS_SECRET_KEY`)を読みます。`BACKUP_S3_ACCESS_KEY_ID` だけでは不十分です。 + +### エラーに `s3://my-bucket/s3Path/...` が現れる + +このバージョンで `BACKUP_S3_PATH` はバケットのサブプレフィックスであり、パススタイルのスイッチではありません。`s3Path` を設定しないでください。Weaviate の S3 クライアントはカスタムエンドポイントに対して自動的にパススタイルを使います。 + +### `check if backup ... exists` が予期しないエラーで失敗する + +コンテナから RustFS に到達できていません。エンドポイントのホストが名前解決でき、バケットが存在することを確認してください。 + +## 次のステップ + +- バックアップの自動化の前に [S3 互換性についての注意](/administration/protocols/s3) を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token) で本番用の専用認証情報を作成してください。 +- [Weaviate バックアップのドキュメント](https://docs.weaviate.io/deploy/configuration/backups) に従い、同じバケットでリストアフィルタ・ロールベースのバックアップ・ファイルシステム代替を活用してください。 diff --git a/content/zh/developer/integration/ai/cocoindex.md b/content/zh/developer/integration/ai/cocoindex.md new file mode 100644 index 000000000..15cb151f1 --- /dev/null +++ b/content/zh/developer/integration/ai/cocoindex.md @@ -0,0 +1,237 @@ +--- +title: "CocoIndex" +description: "用 CocoIndex 把存放在 RustFS 桶中的文档索引成向量。" +--- + +本指南将面向 AI 管道的增量索引引擎 [CocoIndex](https://github.com/cocoindex-io/cocoindex) 连接到 **RustFS** 作为文档源。你将构建一个流:从桶前缀列出 markdown 文件、分块并向量化、把向量存进 Postgres,最后查询索引。整个流程使用 CocoIndex `1.0.26` 通过自定义 S3 端点从 RustFS 桶读取验证通过。 + +你需要 Python 3.11+ 和带 `pgvector` 扩展的 Postgres(流的与状态存储)。 + +## 架构 + +```mermaid +flowchart LR + RustFS["RustFS :9000"] -->|"S3 source: *.md"| Flow["CocoIndex flow"] + Flow -->|"chunks + embeddings"| PG["Postgres + pgvector"] + Query["semantic query"] --> PG +``` + +CocoIndex 通过你自建的 aiobotocore 客户端读取源对象,因此任何 S3 兼容端点都能用——包括路径样式寻址的 RustFS。增量更新只处理内容变化的文件,以稳定的 S3 路径为键。 + +## 1. 准备环境 + +安装带 S3 连接器的 CocoIndex 和 embedding 栈: + +```bash +python3 -m venv .venv +./.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu +./.venv/bin/pip install "cocoindex[amazon_s3]" asyncpg pgvector numpy python-dotenv sentence-transformers +``` + +把源文档上传到桶前缀,替换全部连接占位符: + +```bash +aws s3 cp ./docs s3://my-bucket/cocoindex-docs/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +upload: docs/rag-basics.md to s3://my-bucket/cocoindex-docs/rag-basics.md +upload: docs/rustfs-overview.md to s3://my-bucket/cocoindex-docs/rustfs-overview.md +``` + +## 2. 编写流 + +创建环境文件和流。S3 客户端在 `AWS_ENDPOINT_URL` 已设置时创建,aiobotocore 会据此指向 S3 兼容端点: + +```ini title=".env" +S3_BUCKET=my-bucket +S3_PREFIX=cocoindex-docs/ +AWS_ENDPOINT_URL=http://:9000 +AWS_ACCESS_KEY_ID= +AWS_SECRET_ACCESS_KEY= +AWS_DEFAULT_REGION=us-east-1 +COCOINDEX_DB=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +POSTGRES_URL=postgres://cocoindex:cocoindex@localhost:5432/cocoindex +``` + +```python title="main.py" +import asyncio, os, sys +from dataclasses import dataclass +from typing import AsyncIterator, Annotated + +import aiobotocore.session +import asyncpg +from dotenv import load_dotenv +from numpy.typing import NDArray +from pgvector.asyncpg import register_vector + +load_dotenv() + +import cocoindex as coco +from cocoindex.connectors import amazon_s3, postgres +from cocoindex.ops.sentence_transformers import SentenceTransformerEmbedder +from cocoindex.ops.text import RecursiveSplitter +from cocoindex.resources.chunk import Chunk +from cocoindex.resources.file import PatternFilePathMatcher + +DATABASE_URL = os.environ["POSTGRES_URL"] +TABLE_NAME = "rustfs_doc_embeddings" +PG_SCHEMA_NAME = "coco_examples" +S3_BUCKET = os.environ["S3_BUCKET"] +S3_PREFIX = os.getenv("S3_PREFIX", "") +EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2" +PG_DB = coco.ContextKey[asyncpg.Pool]("db") +S3_CLIENT = coco.ContextKey[object]("s3_client") +EMBEDDER = coco.ContextKey[SentenceTransformerEmbedder]("embedder", detect_change=True) + +_splitter = RecursiveSplitter() + +@coco.lifespan +async def coco_lifespan(builder: coco.EnvironmentBuilder) -> AsyncIterator[None]: + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + builder.provide(PG_DB, pool) + builder.provide(EMBEDDER, SentenceTransformerEmbedder(EMBED_MODEL)) + session = aiobotocore.session.get_session() + async with session.create_client("s3") as s3_client: + builder.provide(S3_CLIENT, s3_client) + yield + +@dataclass +class DocEmbedding: + id: int + filename: str + text: str + embedding: Annotated[NDArray, EMBEDDER] + +@coco.fn +async def process_chunk(chunk: Chunk, filename: str, table: postgres.TableTarget[DocEmbedding]) -> None: + table.declare_row(row=DocEmbedding( + id=abs(hash(f"{filename}:{chunk.start.char_offset}")) % (10 ** 9), + filename=filename, text=chunk.text, + embedding=await coco.use_context(EMBEDDER).embed(chunk.text), + )) + +@coco.fn(memo=True) +async def process_file(file: amazon_s3.S3File, table: postgres.TableTarget[DocEmbedding]) -> None: + text = await file.read_text() + chunks = _splitter.split(text, chunk_size=2000, chunk_overlap=500, language="markdown") + await coco.map(process_chunk, chunks, file.file_path.path.as_posix(), table) + +@coco.fn +async def app_main() -> None: + target_table = await postgres.mount_table_target( + PG_DB, table_name=TABLE_NAME, + table_schema=await postgres.TableSchema.from_class(DocEmbedding, primary_key=["id"]), + pg_schema_name=PG_SCHEMA_NAME, + ) + client = coco.use_context(S3_CLIENT) + files = amazon_s3.list_objects(client, S3_BUCKET, prefix=S3_PREFIX, + path_matcher=PatternFilePathMatcher(included_patterns=["**/*.md"])) + await coco.mount_each(process_file, files.items(), target_table) + +app = coco.App(coco.AppConfig(name="RustFSDocs"), app_main) + +TOP_K = 5 + + +async def query_once( + pool: asyncpg.Pool, + embedder: SentenceTransformerEmbedder, + query: str, + *, + top_k: int = TOP_K, +) -> None: + query_vec = await embedder.embed(query) + async with pool.acquire() as conn: + rows = await conn.fetch( + f""" + SELECT filename, text, embedding <=> $1 AS distance + FROM "{PG_SCHEMA_NAME}"."{TABLE_NAME}" + ORDER BY distance ASC + LIMIT $2 + """, + query_vec, + top_k, + ) + for r in rows: + score = 1.0 - float(r["distance"]) + print(f"[{score:.3f}] {r['filename']}") + print(f" {r['text']}") + print("---") + + +async def query(initial_query: str | None = None) -> None: + embedder = SentenceTransformerEmbedder(EMBED_MODEL) + async with asyncpg.create_pool(DATABASE_URL, init=register_vector) as pool: + if initial_query is not None: + await query_once(pool, embedder, initial_query) + return + while True: + q = input("Enter search query (or Enter to quit): ").strip() + if not q: + break + await query_once(pool, embedder, q) + + +if __name__ == "__main__": + initial = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else None + asyncio.run(query(initial)) +``` + +## 3. 从 RustFS 构建索引 + +```bash +set -a && . ./.env && set +a +./.venv/bin/cocoindex update main +``` + +```text +✅ app_main: 1 total | 1 added +✅ process_file: 2 total | 2 added +``` + +两个 markdown 文件都从 RustFS 桶读出、分块并向量化进 Postgres。用 `main.py` 的入口查询索引。脚本会加载 `.env`,用同一模型计算问题的嵌入,并打印最近的 chunk: + +```bash +./.venv/bin/python main.py "what does RustFS expose" +``` + +```text +[0.163] rag-basics.md + Retrieval augmented generation combines a retriever and a generator. +--- +``` + +查询命中的 chunk 以桶为事实来源——在 RustFS 里编辑文件后重跑 `cocoindex update main`,只会增量重建变化的部分。 + +![RustFS 控制台中的 CocoIndex 源文档](./images/rustfs-cocoindex-source.png) + +## 4. 停止或重置 + +删除已索引的文档: + +```bash +aws s3 rm s3://my-bucket/cocoindex-docs --recursive \ + --endpoint-url http://:9000 +``` + +## 故障排查 + +### `Environment settings must provide Settings.db_path` + +CocoIndex 自己的状态也存 Postgres。把 `COCOINDEX_DB`(目标表用 `POSTGRES_URL`)指向启用了 `pgvector` 扩展的数据库。 + +### 流报 `InvalidAccessKeyId` 或连接超时 + +运行流之前没有导出环境变量(`set -a && . ./.env && set +a`)。`AWS_ENDPOINT_URL` 必须带协议;凭证走标准 `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`。 + +### 流看不到文件 + +检查前缀与匹配器——`list_objects` 遍历 `S3_PREFIX` 并按 `included_patterns` 过滤。先用 `aws s3 ls s3://my-bucket/cocoindex-docs/` 确认对象存在。 + +## 下一步 + +- 在接入更多源之前,先阅读 [S3 兼容性说明](/administration/protocols/s3)。 +- 使用[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。 +- 按照 [CocoIndex Amazon S3 连接器文档](https://cocoindex.io/docs/connectors/amazon_s3)使用路径匹配器、大小限制与实时更新。 diff --git a/content/zh/developer/integration/ai/dify.md b/content/zh/developer/integration/ai/dify.md new file mode 100644 index 000000000..b2fd38802 --- /dev/null +++ b/content/zh/developer/integration/ai/dify.md @@ -0,0 +1,135 @@ +--- +title: "Dify" +description: "把 Dify 的上传文件、知识库文档和系统状态存进 RustFS 桶。" +--- + +本指南将开源 LLM 应用平台 [Dify](https://github.com/langgenius/dify) 通过其 OpenDAL 存储后端连接到 **RustFS**。你将把文件存储从本地磁盘切换到 RustFS 桶,启动栈,向知识库上传文档,并在桶中确认对象。整个流程使用 Dify `1.18.0`(Docker Compose)验证通过。 + +你需要 Docker Compose。本部署用于本地集成测试,不适用于生产环境。 + +## 架构 + +```mermaid +flowchart LR + Console["Console / API"] -->|"files/upload"| RustFS["RustFS :9000"] + RustFS -->|"upload_files, secrets"| API["api / worker"] +``` + +Dify 通过配置的存储后端持久化上传文档、知识库文件和引导密钥(`.dify_secret_key`、工作区密钥)。后端是桶时,这些都不再落在容器磁盘上。 + +## 1. 为 RustFS 配置存储 + +在 `docker/.env`(从 `.env.example` 复制)里把 OpenDAL 切到 S3 scheme: + +```ini title="docker/.env" +STORAGE_TYPE=opendal +OPENDAL_SCHEME=s3 +OPENDAL_S3_ENDPOINT=http://:9000 +OPENDAL_S3_BUCKET=dify +OPENDAL_S3_ACCESS_KEY_ID= +OPENDAL_S3_SECRET_ACCESS_KEY= +OPENDAL_S3_REGION=us-east-1 +OPENDAL_S3_ENABLE_PATH_STYLE=true +OPENDAL_S3_ROOT=/ +``` + +启动栈前先建桶: + +```bash +aws s3 mb s3://dify --endpoint-url http://:9000 +``` + +:::note[把 RustFS 接入 Compose 网络] + +Compose 栈在自己的 bridge 网络里,而 Docker 会隔离不同 bridge——`http://172.17.0.2:9000` 这类端点在 `api` 容器里会连接超时。把 RustFS 容器以别名接入 Compose 网络,端点主机用别名: + +```bash +docker network connect --alias rustfs +``` + +修改 `.env` 后要重建整个栈——`docker compose restart` 不会重读环境变量。 + +::: + +## 2. 启动栈并初始化 + +```bash +cd dify/docker +docker compose up -d +``` + +等 `api` 健康检查通过,在 Web UI(`http://localhost:80`)创建管理员账号。Dify 会立刻把引导状态写进桶: + +```bash +aws s3 ls s3://dify/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 14:31:00 65 .dify_secret_key +2026-11-01 14:33:06 1674 privkeys//private.pem +``` + +密钥与工作区私钥现在都在 RustFS——容器里没有值得保留的状态。 + +## 3. 上传知识库文档 + +在 UI 里创建知识库,然后上传文档。上传会落到桶的 `upload_files//` 下: + +```bash +aws s3 ls s3://dify/upload_files/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 15:25:53 128 upload_files//0ae369a1-70ed-40e8-b3d9-0f12d0b7c699.txt +``` + +上传完成的瞬间对象即出现——索引流程直接针对桶内副本运行。 + +![RustFS 控制台中的 Dify 上传文件](./images/rustfs-dify-uploads.png) + +## 4. 停止或重置 + +保留桶内对象并拆除栈: + +```bash +docker compose down +``` + +删除 Dify 数据: + +```bash +aws s3 rm s3://dify --recursive \ + --endpoint-url http://:9000 +``` + +:::warning[重置时记得清 bind mount] + +Dify 的 Compose 文件把数据库和存储 bind-mount 在 `docker/volumes/` 下。`docker compose down -v` 不会删除 bind mount——需要干净环境时显式删除 `docker/volumes/`,否则旧管理员账号和加密状态会残留。 + +::: + +## 故障排查 + +### 启动日志对桶报 `tcp connect error: Connection timed out` + +栈到不了 RustFS 地址——Docker bridge 之间的网络隔离。按第 1 步把 RustFS 以别名接入 Compose 网络。 + +### 登录报 `Invalid encrypted data` + +管理员密码字段由前端做 Base64 编码;直接给 console API 发明文会失败。账号与密码操作请走 Web UI,或按前端方式编码字段。 + +### 创建文档报 `Default model not found for text-embedding` + +`high-quality` 索引模式需要在 Dify 里配置 embedding 模型供应商。纯存储测试用 `economy` 索引,或先配置模型供应商。 + +### 上传仍落在本地磁盘 + +`api` 和 `worker` 容器还是 `.env` 修改前的旧实例。用 `docker compose up -d --force-recreate` 重建整个栈,让每个服务都读到新存储配置。 + +## 下一步 + +- 在扩展大型知识库前,先阅读 [S3 兼容性说明](/administration/protocols/s3)。 +- 使用[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。 +- 按照 [Dify 环境变量参考](https://docs.dify.ai/en/self-host/deploy/configuration/environments)了解插件守护进程独立的 S3 设置与同一桶上的分段上传调优。 diff --git a/content/zh/developer/integration/ai/feast.md b/content/zh/developer/integration/ai/feast.md new file mode 100644 index 000000000..7258b8aef --- /dev/null +++ b/content/zh/developer/integration/ai/feast.md @@ -0,0 +1,164 @@ +--- +title: "Feast" +description: "把 Feast 的特征注册表和离线 Parquet 源存放在 RustFS 桶中。" +--- + +本指南将开源特征存储 [Feast](https://github.com/feast-dev/feast) 连接到 **RustFS**,同时承担两个存储角色:特征注册表(`registry.db`)放在桶里,离线特征源是同一桶里的 Parquet 文件。你将执行 `feast apply`、把特征从 RustFS 物化进在线存储,再读回。整个流程使用 Feast `0.67.0` 验证通过。 + +你需要 Python 3.10+。本部署用于本地集成测试,不适用于生产环境。 + +## 架构 + +```mermaid +flowchart LR + Apply["feast apply"] -->|"registry.db"| RustFS["RustFS :9000"] + RustFS -->|"parquet offline read"| Materialize["feast materialize"] + Materialize -->|"features"| Online["SQLite online store"] + Query["get_online_features"] --> Online +``` + +注册表存储通过 boto3 读写桶里的 `registry.db`,文件离线存储通过 s3fs 读 Parquet——两者都支持自定义端点,因此整个特征历史层都在桶上,在线存储保持本地。 + +## 1. 安装带 S3 支持的 Feast + +基础包不含 S3 客户端,需要显式安装: + +```bash +python3 -m venv .venv +./.venv/bin/pip install feast boto3 s3fs +``` + +上传离线特征数据,替换全部连接占位符: + +```bash +aws s3 cp driver_stats.parquet s3://my-bucket/feast/driver_stats.parquet \ + --endpoint-url http://:9000 +``` + +## 2. 配置仓库 + +创建仓库文件。注册表是普通的 `s3://` URI,端点覆盖来自 `FEAST_S3_ENDPOINT_URL` 环境变量;数据源自带 `s3_endpoint_override`: + +```yaml title="feature_store.yaml" +project: rustfs_demo +provider: local +registry: s3://my-bucket/feast/registry.db +offline_store: + type: file +entity_key_serialization_version: 3 +``` + +```python title="features.py" +from datetime import timedelta +from feast import Entity, FeatureView, Field, FileSource +from feast.types import Float32, Int64 + +driver = Entity(name="driver", join_keys=["driver_id"]) +source = FileSource( + name="driver_stats_source", + path="s3://my-bucket/feast/driver_stats.parquet", + timestamp_field="event_timestamp", + s3_endpoint_override="http://:9000", +) +driver_stats = FeatureView( + name="driver_stats", + entities=[driver], + ttl=timedelta(days=1), + schema=[Field(name="conv_rate", dtype=Float32), Field(name="avg_daily_trips", dtype=Int64)], + source=source, +) +``` + +为注册表客户端导出端点和凭证: + +```bash +export FEAST_S3_ENDPOINT_URL=http://:9000 +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= +export AWS_DEFAULT_REGION=us-east-1 +``` + +## 3. 执行 feast apply 并物化 + +`feast apply` 把 `registry.db` 写进桶;`materialize-incremental` 把 RustFS 里的 Parquet 特征读进本地在线存储: + +```bash +./.venv/bin/feast apply +./.venv/bin/feast materialize-incremental 2026-11-02T00:00:00Z +``` + +```text +Created entity driver +Created feature view driver_stats +... +driver_stats from 2026-10-31 ... to 2026-11-02 00:00:00+00:00: +``` + +确认注册表对象已在 RustFS: + +```bash +aws s3 ls s3://my-bucket/feast/ \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:57:58 1322 registry.db +2026-11-01 13:56:43 3680 driver_stats.parquet +``` + +![RustFS 控制台中的 Feast 注册表与特征数据](./images/rustfs-feast-registry.png) + +## 4. 读回特征 + +```bash +./.venv/bin/python - <<'PY' +from feast import FeatureStore +store = FeatureStore(repo_path=".") +res = store.get_online_features( + features=["driver_stats:conv_rate", "driver_stats:avg_daily_trips"], + entity_rows=[{"driver_id": 101}], +).to_dict() +print("conv_rate:", res["conv_rate"][0]) +print("avg_daily_trips:", res["avg_daily_trips"][0]) +PY +``` + +```text +conv_rate: 0.699999988079071 +avg_daily_trips: 130 +``` + +被服务的特征来自 RustFS 存储的 Parquet 文件物化而来。 + +## 5. 停止或重置 + +删除仓库对象: + +```bash +aws s3 rm s3://my-bucket/feast --recursive \ + --endpoint-url http://:9000 +``` + +## 故障排查 + +### `Could not import module 'feast.infra.registry.s3'` + +S3 注册表存储需要 `boto3`,基础 Feast 包不安装它。按第 1 步 `pip install boto3`(离线存储还要 `s3fs`)。 + +### 物化时报 `Install s3fs to access S3` + +文件离线存储通过 `s3fs` 读 Parquet。与 `boto3` 一起安装。 + +### 注册表 S3 存储忽略端点 + +注册表只从 `FEAST_S3_ENDPOINT_URL` 环境变量读端点——普通的 `AWS_ENDPOINT_URL` 在这里无效。`FileSource` 用自己的 `s3_endpoint_override`;两者都要设置。 + +### 出现实体键序列化的弃用警告 + +在 `feature_store.yaml` 里设 `entity_key_serialization_version: 3`——低于 3 的版本对新在线存储已不接受。 + +## 下一步 + +- 在把生产注册表指向桶之前,先阅读 [S3 兼容性说明](/administration/protocols/s3)。 +- 使用[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。 +- 按照 [Feast 文档](https://docs.feast.dev/)在同一个桶上使用流式源、特征服务与注册表替代方案。 diff --git a/content/zh/developer/integration/ai/images/rustfs-cocoindex-source.png b/content/zh/developer/integration/ai/images/rustfs-cocoindex-source.png new file mode 100644 index 000000000..c041071aa Binary files /dev/null and b/content/zh/developer/integration/ai/images/rustfs-cocoindex-source.png differ diff --git a/content/zh/developer/integration/ai/images/rustfs-dify-uploads.png b/content/zh/developer/integration/ai/images/rustfs-dify-uploads.png new file mode 100644 index 000000000..5ccfbdca8 Binary files /dev/null and b/content/zh/developer/integration/ai/images/rustfs-dify-uploads.png differ diff --git a/content/zh/developer/integration/ai/images/rustfs-feast-registry.png b/content/zh/developer/integration/ai/images/rustfs-feast-registry.png new file mode 100644 index 000000000..31fab83a1 Binary files /dev/null and b/content/zh/developer/integration/ai/images/rustfs-feast-registry.png differ diff --git a/content/zh/developer/integration/ai/images/rustfs-ragflow-docs.png b/content/zh/developer/integration/ai/images/rustfs-ragflow-docs.png new file mode 100644 index 000000000..1619785a3 Binary files /dev/null and b/content/zh/developer/integration/ai/images/rustfs-ragflow-docs.png differ diff --git a/content/zh/developer/integration/ai/meta.json b/content/zh/developer/integration/ai/meta.json index f03ec4897..4deb8701f 100644 --- a/content/zh/developer/integration/ai/meta.json +++ b/content/zh/developer/integration/ai/meta.json @@ -4,6 +4,10 @@ "mlflow", "ray", "sglang", - "vllm" + "vllm", + "dify", + "ragflow", + "cocoindex", + "feast" ] } diff --git a/content/zh/developer/integration/ai/ragflow.md b/content/zh/developer/integration/ai/ragflow.md new file mode 100644 index 000000000..21d6bf79f --- /dev/null +++ b/content/zh/developer/integration/ai/ragflow.md @@ -0,0 +1,144 @@ +--- +title: "RAGFlow" +description: "让 RAGFlow 的上传文档与工作区状态存放在 RustFS 桶中。" +--- + +本指南将开源 RAG 引擎 [RAGFlow](https://github.com/infiniflow/ragflow) 连接到 **RustFS** 作为其对象存储。RAGFlow 通过 MinIO 兼容的客户端配置把每个上传文档和解析产物存进 S3 兼容存储。你将把该配置指向 RustFS,启动栈,向知识库上传文档,并在桶中确认对象。整个流程使用 `infiniflow/ragflow:v1.0.0-rc3`(Infinity 文档引擎)验证通过。 + +你需要 Docker Compose。本部署用于本地集成测试,不适用于生产环境。 + +## 架构 + +```mermaid +flowchart LR + Upload["Knowledge base upload"] --> API["RAGFlow API :9380"] + API -->|"documents"| RustFS["RustFS :9000"] + API --> Doc["Infinity / Elasticsearch"] +``` + +每个租户获得一个以其租户 ID 命名的桶,每个上传文件都是该桶下的一个对象。解析会在源文档旁写入更多产物。 + +## 1. 配置栈指向 RustFS + +克隆 RAGFlow 并编辑 `docker/.env`。选择 Infinity 文档引擎,并把存储客户端指向 RustFS: + +```ini title="docker/.env" +DOC_ENGINE=infinity +MINIO_HOST= +MINIO_USER= +MINIO_PASSWORD= +``` + +`docker/service_conf.yaml.template` 的 `minio:` 段由这些变量渲染,所以同一组字段驱动任意 S3 兼容端点。RAGFlow 会在首次上传时自动为每个租户创建桶——无需预建。 + +:::note[给 RustFS 容器加网络别名] + +Compose 栈在自己的 bridge 网络里,而 Docker 会隔离不同 bridge,因此 RustFS 容器的 `172.17.0.x` 地址对栈不可达。把 RustFS 以别名接入 Compose 网络,并把别名用作 `MINIO_HOST`: + +```bash +docker network connect --alias rustfs ragflow_ragflow +``` + +如果你的镜像仓库拉不到内置 MinIO 镜像(来自 quay.io),可以替换它——`MINIO_HOST` 指向别处时栈根本不会访问它。 + +::: + +## 2. 启动栈 + +```bash +cd ragflow/docker +docker compose -p ragflow up -d +``` + +等 API 起来后,确认服务加载的存储配置: + +```bash +docker logs ragflow-cpu 2>&1 | grep "minio:" +``` + +```text +minio: {'user': '...', 'password': '...', 'host': 'rustfs:9000', 'bucket': '', 'prefix_path': ''} +``` + +`bucket` 为空是预期行为:RAGFlow 会在首次上传时为每个租户建桶。 + +## 3. 向知识库上传文档 + +创建用户和 API key(通过 `https://localhost:443` 的 Web UI,或用户 API),然后走 HTTP API: + +```bash +curl -s -X POST http://localhost:9380/api/v1/datasets \ + -H "Authorization: Bearer " -H "Content-Type: application/json" \ + -d '{"name":"rustfs-kb"}' + +curl -s -X POST "http://localhost:9380/api/v1/datasets//documents" \ + -H "Authorization: Bearer " \ + -F "file=@rustfs-overview.txt" +``` + +```json +{"code":0,"data":[{"chunk_method":"naive","location":"rustfs-overview.txt","name":"rustfs-overview.txt","run":"UNSTART"}]} +``` + +确认对象已落 RustFS——租户桶以租户 ID 命名: + +```bash +aws s3 ls s3:/// --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 16:02:41 204 rg-doc.txt +``` + +读回对象并与上传文件比对: + +```bash +aws s3 cp s3:///rg-doc.txt - \ + --endpoint-url http://:9000 +``` + +![RustFS 控制台中的 RAGFlow 上传文档](./images/rustfs-ragflow-docs.png) + +## 4. 解析与检索 + +文档解析(`PUT /api/v1/datasets/{id}/documents/{doc_id}` 带 `{"run":"parse"}`)会从 RustFS 消费已存储的对象,并把分块产物写到旁边。解析还需要在 RAGFlow 中配置 embedding 模型——该步骤取决于你的模型配置,与存储无关。 + +## 5. 停止或重置 + +保留桶内对象并拆除栈: + +```bash +docker compose -p ragflow stop +``` + +删除租户数据: + +```bash +aws s3 rm s3:// --recursive \ + --endpoint-url http://:9000 +``` + +## 故障排查 + +### 上传成功但 RustFS 里没有对象 + +服务还在连内置 MinIO。看启动日志里的 `minio:` 行——如果 host 不是你的 RustFS 别名,说明 `.env` 的修改没进容器;用 `docker compose -p ragflow up -d --force-recreate ragflow-cpu` 重建。 + +### 启动日志出现 `tcp connect error: Connection timed out` + +RustFS 容器地址对 Compose 网络不可达。按第 1 步把 RustFS 以别名接入 Compose 网络,并把 `MINIO_HOST` 设为别名。 + +### `/api/v1` 报 `Authentication error: API key is invalid!` + +`/api/v1` SDK 路由接受 RAGFlow API key(Web UI 里创建),不是登录 access token。`/v1/*` 路由走登录会话。 + +### 注册或登录报密码错误 + +RAGFlow 要求密码先经其内置 RSA 公钥加密再到达 API——Web UI 会自动处理。除非复现客户端加密,否则请用 UI 创建账号。 + +## 下一步 + +- 在大规模接入前,先阅读 [S3 兼容性说明](/administration/protocols/s3)。 +- 使用[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。 +- 按照 [RAGFlow 文档](https://ragflow.io/docs/dev/)在同一个桶上使用分块模板、embedding 模型与 Agent 工作流。 diff --git a/content/zh/developer/integration/database/images/rustfs-qdrant-snapshots.png b/content/zh/developer/integration/database/images/rustfs-qdrant-snapshots.png new file mode 100644 index 000000000..1467f45c6 Binary files /dev/null and b/content/zh/developer/integration/database/images/rustfs-qdrant-snapshots.png differ diff --git a/content/zh/developer/integration/database/images/rustfs-weaviate-backup.png b/content/zh/developer/integration/database/images/rustfs-weaviate-backup.png new file mode 100644 index 000000000..772f3052c Binary files /dev/null and b/content/zh/developer/integration/database/images/rustfs-weaviate-backup.png differ diff --git a/content/zh/developer/integration/database/meta.json b/content/zh/developer/integration/database/meta.json index 2d7563d5c..02999b561 100644 --- a/content/zh/developer/integration/database/meta.json +++ b/content/zh/developer/integration/database/meta.json @@ -9,6 +9,8 @@ "lancedb", "milvus", "trino", - "vitess" + "vitess", + "qdrant", + "weaviate" ] } diff --git a/content/zh/developer/integration/database/qdrant.md b/content/zh/developer/integration/database/qdrant.md new file mode 100644 index 000000000..d10b0cc33 --- /dev/null +++ b/content/zh/developer/integration/database/qdrant.md @@ -0,0 +1,133 @@ +--- +title: "Qdrant" +description: "通过 S3 快照存储把 Qdrant 集合快照存放到 RustFS 桶。" +--- + +本指南将开源向量数据库 [Qdrant](https://github.com/qdrant/qdrant)(面向 AI 搜索与 RAG)连接到 **RustFS** 作为其快照存储。你将启用 S3 快照存储,创建集合并插入向量,把快照上传进桶,再在全新节点上恢复它。整个流程使用 `qdrant/qdrant:v1.20.0` 以路径样式寻址向 RustFS 桶写入快照验证通过。 + +你需要 Docker。本部署用于本地集成测试,不适用于生产环境。 + +## 架构 + +```mermaid +flowchart LR + API["Qdrant REST :6333"] -->|"snapshot"| S3["RustFS :9000"] + S3 -->|"recover"| Fresh["Fresh Qdrant node"] +``` + +启用 `snapshots_storage: s3` 后,每个集合快照都会上传到桶的 `/snapshots//` 下,指向同一个桶的新节点无需本地文件即可重建任意集合。 + +## 1. 让 Qdrant 指向 RustFS + +通过环境变量配置快照存储——`QDRANT__` 前缀映射到配置树,`S3_CONFIG__ENDPOINT_URL` 是 MinIO 类存储的自定义端点字段。桶需预先创建;前缀可以为空。 + +```bash +docker run -d --name qdrant -p 6333:6333 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__SNAPSHOTS_STORAGE=s3 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__BUCKET=my-bucket \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__PREFIX=qdrant \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__REGION=us-east-1 \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ACCESS_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__SECRET_KEY= \ + -e QDRANT__STORAGE__SNAPSHOTS_CONFIG__S3_CONFIG__ENDPOINT_URL=http://:9000 \ + qdrant/qdrant:v1.20.0 +``` + +:::note[注意 QDRANT__STORAGE__SNAPSHOTS_CONFIG 路径] + +已发布版本的配置在 `storage.snapshots_config` 下(不是 `storage.snapshots`),S3 段的端点键是 `endpoint_url`。挂载带旧键名的 `custom_config.yaml` 会被静默忽略——快照仍会写进本地 `./snapshots` 目录。验证方式:打一次快照后检查本地目录是否为空。 + +::: + +## 2. 创建集合并打快照 + +创建集合、插入向量、请求快照: + +```bash +curl -s -X PUT http://localhost:6333/collections/demo \ + -H "Content-Type: application/json" \ + -d '{"vectors":{"size":4,"distance":"Dot"}}' + +curl -s -X PUT "http://localhost:6333/collections/demo/points?wait=true" \ + -H "Content-Type: application/json" \ + -d '{"points":[{"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"city":"Berlin"}},{"id":2,"vector":[0.9,0.8,0.7,0.6],"payload":{"city":"Tokyo"}}]}' + +curl -s -X POST http://localhost:6333/collections/demo/snapshots +``` + +```json +{"result":{"name":"demo-8437507706552082-2026-11-01-13-31-15-0.snapshot","size":64512},"status":"ok"} +``` + +确认快照对象已落在 RustFS,替换全部连接占位符: + +```bash +aws s3 ls s3://my-bucket/qdrant/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:31:15 64512 qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot +``` + +![RustFS 控制台中的 Qdrant 快照对象](./images/rustfs-qdrant-snapshots.png) + +## 3. 在全新节点上恢复 + +快照恢复到同名集合。清空本地节点(或另起一个节点)指向同一个桶,从 RustFS 下载快照,经恢复 API 上传: + +```bash +aws s3 cp "s3://my-bucket/qdrant/snapshots/demo/demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" . \ + --endpoint-url http://:9000 + +curl -s -X POST "http://localhost:6333/collections/demo/snapshots/upload?priority=snapshot" \ + -F "snapshot=@demo-8437507706552082-2026-11-01-13-31-15-0.snapshot" +``` + +验证恢复的数据: + +```bash +curl -s -X POST http://localhost:6333/collections/demo/points/scroll \ + -H "Content-Type: application/json" -d '{"limit":2,"with_payload":true}' +``` + +```json +{"result":{"points":[{"id":1,"payload":{"city":"Berlin"}},{"id":2,"payload":{"city":"Tokyo"}}]},"status":"ok"} +``` + +向量与 payload 全部从 RustFS 存储的快照恢复回来。 + +## 4. 停止或重置 + +保留桶内对象并拆除演示环境: + +```bash +docker rm -f qdrant +``` + +删除已存储的快照: + +```bash +aws s3 rm s3://my-bucket/qdrant --recursive \ + --endpoint-url http://:9000 +``` + +## 故障排查 + +### 快照仍出现在容器的 `/qdrant/snapshots` 下 + +存储切换没有生效——环境变量路径写错,或旧配置文件覆盖了它。严格按第 1 步使用 `QDRANT__STORAGE__SNAPSHOTS_CONFIG__*` 变量并重启容器;然后确认本地快照目录保持为空。 + +### `Wrong input: Snapshot is not compatible with existing collection` + +目标集合已存在且模式不同。恢复前先删除空的或过期的集合——上传 API 会按快照创建集合。 + +### 打完快照桶里没有对象 + +桶名或端点错误。端点必须带协议,桶必须存在;对象 key 是 `/snapshots//.snapshot`,请递归列出。 + +## 下一步 + +- 在规划快照备份前,先阅读 [S3 兼容性说明](/administration/protocols/s3)。 +- 使用[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。 +- 按照 [Qdrant 快照文档](https://qdrant.tech/documentation/snapshots/)在同一个桶上使用全量存储快照、分片级快照与版本兼容性管理。 diff --git a/content/zh/developer/integration/database/weaviate.md b/content/zh/developer/integration/database/weaviate.md new file mode 100644 index 000000000..ae463934b --- /dev/null +++ b/content/zh/developer/integration/database/weaviate.md @@ -0,0 +1,148 @@ +--- +title: "Weaviate" +description: "用 backup-s3 模块把 Weaviate 集合备份到 RustFS 桶。" +--- + +本指南将开源向量数据库 [Weaviate](https://github.com/weaviate/weaviate)(面向 AI 搜索与 RAG)通过其 `backup-s3` 模块连接到 **RustFS**。你将启用该模块,创建集合并插入向量,在桶中创建备份,再执行恢复。整个流程使用 `semitechnologies/weaviate:1.31.0` 向 RustFS 桶备份验证通过。 + +你需要 Docker。本部署用于本地集成测试,不适用于生产环境。 + +## 架构 + +```mermaid +flowchart LR + Weaviate["Weaviate :8080"] -->|"backup create"| RustFS["RustFS :9000"] + RustFS -->|"backup restore"| Weaviate +``` + +备份会把 `backup_config.json`、每个类的 `backup.json` 和数据分块写入桶前缀 `/`,恢复时按原集合名读回。 + +## 1. 启用 backup-s3 模块 + +带模块和 S3 设置启动 Weaviate。凭证走标准 AWS 变量——Weaviate 1.31 的模块读取 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY`,不读 `BACKUP_S3_ACCESS_KEY_ID`: + +```bash +docker run -d --name weaviate -p 8080:8080 \ + -e QUERY_DEFAULTS_LIMIT=20 \ + -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \ + -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \ + -e ENABLE_MODULES=backup-s3 \ + -e BACKUP_S3_BUCKET=my-bucket \ + -e AWS_REGION=us-east-1 \ + -e AWS_ACCESS_KEY_ID= \ + -e AWS_SECRET_ACCESS_KEY= \ + -e BACKUP_S3_ENDPOINT=:9000 \ + -e BACKUP_S3_USE_SSL=false \ + -e CLUSTER_HOSTNAME=weaviate-demo \ + semitechnologies/weaviate:1.31.0 +``` + +:::note[端点格式与凭证] + +`BACKUP_S3_ENDPOINT` 只接受不带协议的 `host:port`——模块背后的 AWS SDK Go v1 对 `http://...` 形式会报 `Endpoint url cannot have fully qualified paths`。TLS 由 `BACKUP_S3_USE_SSL=false` 控制,请求为路径样式。误传 `BACKUP_S3_ACCESS_KEY_ID` 而不是 `AWS_ACCESS_KEY_ID` 时客户端是匿名的,每次备份都会报 `Access Denied`。 + +::: + +确认模块已加载: + +```bash +curl -s http://localhost:8080/v1/meta | grep -o "backup-s3" +``` + +## 2. 创建集合并备份 + +Weaviate 1.31 用 `POST /v1/schema` 建集合。插入两个对象后发起备份: + +```bash +curl -s -X POST http://localhost:8080/v1/schema \ + -H "Content-Type: application/json" \ + -d '{"class":"Doc","vectorizer":"none","properties":[{"name":"title","dataType":["text"]}]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"RustFS vector backup"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/objects -H "Content-Type: application/json" \ + -d '{"class":"Doc","properties":{"title":"Weaviate on object storage"},"vector":[0.11,0.22,0.33,0.44]}' + +curl -s -X POST http://localhost:8080/v1/backups/s3 -H "Content-Type: application/json" \ + -d '{"id":"rustfs-demo"}' +``` + +```json +{"backend":"s3","classes":["Doc"],"id":"rustfs-demo","path":"s3://my-bucket/rustfs-demo","status":"STARTED"} +``` + +等状态到 `SUCCESS`,确认对象已在 RustFS,替换全部连接占位符: + +```bash +curl -s http://localhost:8080/v1/backups/s3/rustfs-demo +aws s3 ls s3://my-bucket/rustfs-demo/ --recursive \ + --endpoint-url http://:9000 +``` + +```text +2026-11-01 13:46:10 304 rustfs-demo/backup_config.json +2026-11-01 13:46:08 1406 rustfs-demo/weaviate-demo/Doc/chunk-1 +2026-11-01 13:46:08 27666 rustfs-demo/weaviate-demo/backup.json +``` + +![RustFS 控制台中的 Weaviate 备份对象](./images/rustfs-weaviate-backup.png) + +## 3. 恢复 + +把备份恢复进 Weaviate(干净恢复先删掉在线集合): + +```bash +curl -s -X POST http://localhost:8080/v1/backups/s3/rustfs-demo/restore \ + -H "Content-Type: application/json" -d '{}' +``` + +查询恢复后的数据: + +```bash +curl -s -X POST http://localhost:8080/v1/graphql -H "Content-Type: application/json" \ + -d '{"query":"{Get{Doc(limit:2){title}}}"}' +``` + +```json +{"data":{"Get":{"Doc":[{"title":"RustFS vector backup"},{"title":"Weaviate on object storage"}]}}} +``` + +## 4. 停止或重置 + +保留桶内对象并拆除演示环境: + +```bash +docker rm -f weaviate +``` + +删除已存储的备份: + +```bash +aws s3 rm s3://my-bucket/rustfs-demo --recursive \ + --endpoint-url http://:9000 +``` + +## 故障排查 + +### 启动报 `Endpoint url cannot have fully qualified paths` + +`BACKUP_S3_ENDPOINT` 带了协议。改用纯 `host:port` 并设置 `BACKUP_S3_USE_SSL=false`。 + +### 创建备份时报 `Access Denied` + +模块没拿到凭证。Weaviate 1.31 的 S3 客户端读环境变量 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY`(或 `AWS_ACCESS_KEY`/`AWS_SECRET_KEY`)——只设 `BACKUP_S3_ACCESS_KEY_ID` 不够。 + +### 错误里出现 `s3://my-bucket/s3Path/...` + +该版本里 `BACKUP_S3_PATH` 是桶内子前缀,不是路径样式开关——不要设成 `s3Path`。Weaviate 的 S3 客户端对自定义端点自动使用路径样式。 + +### `check if backup ... exists` 报意外错误 + +容器到 RustFS 不通。确认端点主机可解析且桶存在。 + +## 下一步 + +- 在自动化备份计划前,先阅读 [S3 兼容性说明](/administration/protocols/s3)。 +- 使用[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。 +- 按照 [Weaviate 备份文档](https://docs.weaviate.io/deploy/configuration/backups)在同一个桶上使用恢复过滤、基于角色的备份与文件系统备选方案。