Alan Dokumentation

German

English

German

English

Appearance

Per API chatten ​

Um die Chat-Funktionen von Alan über die API zu nutzen, stehen Ihnen zwei Optionen zur Verfügung:

  1. OpenAI-kompatible API-Schnittstelle: Sie können die OpenAI-kompatible API-Schnittstelle von Alan verwenden, wenn Sie keine Alan-spezifischen Funktionen benötigen. Diese Schnittstelle ist besonders nützlich, wenn Sie bereits OpenAI-Clients oder -Bibliotheken in Ihrer Anwendung einsetzen oder wenn Sie leichtgewichtig Antworten generieren möchten.
  2. Direkte Nutzung der Alan-Chats-API: Alternativ können Sie die Chat-Funktionen direkt über die Alan-/chats/-API-Endpunkte ansprechen. Dies ermöglicht eine nahtlose Integration der Chat-Funktionalitäten in Ihre Anwendungen mit allen Alan-spezifischen Funktionen.

OpenAI-kompatible API-Schnittstelle von Alan ​

In diesem Abschnitt finden Sie die notwendigen Schritte zur Nutzung von Alan über die OpenAI-kompatible API-Schnittstelle. Dies ermöglicht es, Alan sowohl direkt mittels des offiziellen OpenAI-Clients als auch indirekt mittels anderer OpenAI-kompatibler Software zu verwenden.

Die erhaltenen Antworten werden nicht als Chats persistiert und sind somit auch nicht in der Alan-Benutzeroberfläche sichtbar. Beachten Sie außerdem, dass diese Endpunkte keine Alan-spezifischen Funktionen wie Wissensdatenbanken, Experten oder Fähigkeiten unterstützen.

Bereitgestellte Endpunkte ​

Zur Nutzung mit OpenAI-kompatibler Software bietet Alan verschiedene Endpunkte an. Diese sind:

  • GET /oai/models: Listet alle verfügbaren Modelle auf, die über die OpenAI-kompatible API genutzt werden können, und wird genutzt, um den Status der bereitgestellten Modelle zu prüfen.

  • GET /oai/models/{model}: Ruft detaillierte Informationen zu einem spezifischen Modell ab.

  • GET /oai/chat/completions: Generiert Textantworten basierend auf einer Chat-Historie.

  • GET /oai/embeddings: Erzeugt Embeddings aus Texten.

Die bereitgestellten Endpunkte entsprechen im erwarteten Input und erzeugten Output den offiziellen OpenAI-Endpunkten.

Nutzung des offiziellen OpenAI-Clients ​

Im Folgenden soll anhand eines Codebeispiels demonstriert werden, wie Sie Alan mittels des offiziellen OpenAI-Clients nutzen. Dabei können sowohl der asynchrone als auch der synchrone OpenAI-Client verwendet werden.

Vorbereitung ​

Die Nutzung von Alan mittels OpenAI-Client erfordert einen gültigen Alan-API-Key.

Synchroner Client ​
python
from openai import OpenAI

api_key = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"
base_url = "https://app.alan.de/api/v1/oai"

sync_client = OpenAI(api_key=api_key, base_url=base_url)
Asynchroner Client ​
python
from openai import AsyncOpenAI

api_key = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"
base_url = "https://app.alan.de/api/v1/oai"

async_client = AsyncOpenAI(api_key=api_key, base_url=base_url)

Verfügbare Modelle und spezifische Modellinformationen abrufen ​

Sie können alle verfügbaren Modelle und deren Status abrufen. Das Antwortschema entspricht dem OpenAI-Format.

python
print(sync_client.models.list())

model = "comma-soft/comma-llm-agentic"
print(sync_client.models.retrieve(model))

Chat Completions erzeugen ​

Um mit einem Modell zu chatten, nutzen Sie den Chat-Completions-Endpunkt. Hierbei werden Textantworten generiert basierend auf einer Chat-Historie, welche dem OpenAI-Standard entspricht. Bei der Nutzung des Endpunkts werden neben messages, model und stream abhängig vom Modell lediglich die folgenden Parameter berücksichtigt: temperature, top_p, max_token. Die Wertebereiche und Typen der Parameter sowie das Antwortformat entsprechen dem OpenAI-Standard.

Streaming Response ​
python
completion = sync_client.chat.completions.create(
    messages=[{"role": "user", "content": "Wie geht es dir?"}],
    model="comma-soft/comma-llm-agentic",
    temperature=...,
    top_p=...,
    max_token=...,
    stream=True
)

for chunk in completion:
    print(chunk)
Non-Streaming Response ​
python
completion = sync_client.chat.completions.create(
    messages=[{"role": "user", "content": "Wie geht es dir?"}],
    model="comma-soft/comma-llm-agentic",
    stream=False
)

print(completion)

Embeddings ​

Darüber hinaus können Sie Embeddings generieren, also einen numerischen Vektor für einen gegebenen Input-Text berechnen. Dabei können alle zur Verfügung stehenden Parameter genutzt werden.

python
embeddings = sync_client.embeddings.create(input="Dies ist ein Text!", model="comma-soft/comma-embedding-20251125")
print(embeddings)

Einschränkungen ​

Zum jetzigen Zeitpunkt unterstützen wir lediglich die Basisfunktionalität wie oben beschrieben. Eine Erweiterung um fortgeschrittene Features wie Guided Generation oder Beam Search steht aktuell nicht zur Verfügung.

Alan Chats-API ​

Um die vollumfänglichen Chat-Funktionen von Alan zu nutzen, können Sie die Alan-Chats-API-Endpunkte direkt ansprechen. Diese Endpunkte sind komplexer in der Nutzung, unterstützen jedoch alle Alan-spezifischen Funktionen wie Wissensdatenbanken, Experten und Fähigkeiten.

Eine vollständige Übersicht über die verfügbaren Endpunkte und deren Nutzung finden Sie in der Swagger-Dokumentation.

Im Folgenden werden die grundsätzlichen Schritte zur Nutzung der Chats-API beschrieben und mit Beispielcode in Python veranschaulicht.

Mit Alan chatten ​

Um Antworten von Alan zu erhalten, müssen Sie zunächst einen neuen Chat starten und können dann Anfragen an diesen Chat senden.

Initiale Anfrage senden ​

Um einen neuen Chat mit Alan zu starten, senden Sie Ihre initiale Anfrage an den Endpunkt POST /chats/.

python
import requests
import json

API_KEY = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"

url = "https://app.alan.de/api/v1/chats/"

headers = {"accept": "application/json", "Content-Type": "application/json",  "Authorization": f"Bearer {API_KEY}"}

payload = json.dumps({
  "content": "Schreibe einen ansprechenden LinkedIn Post über die Bedeutung der KI für den Wirtschaftsstandort Deutschland.",
  "settings": {
    "model": "comma-soft/comma-llm-agentic"
  }
})

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)  # SSE-Event-Stream

Standardmäßig sind alle Chats, die Sie über diesen Endpunkt erstellen, sowohl per API nutzbar als auch in der Alan-Benutzeroberfläche sichtbar.

Um einen Chat über die API zu starten, der nicht in der Alan-Benutzeroberfläche sichtbar sein soll, setzen Sie im Request den Parameter api_only auf True.

Antworten verarbeiten ​

Die Antworten von Alan werden im SSE-Format zurückgegeben und müssen entsprechend verarbeitet werden.

Im folgenden Beispiel werden die Chat- und Nachrichten-Objekte aus dem SSE-Stream extrahiert und ausgegeben.

python
chat_response = response.text

# SSE-Antwort extrahieren
events = [
    json.loads(event)
    for event_line in chat_response.split("\n\n")
    if (event := event_line.removeprefix("data:").strip())
]

# Chat-Zustand aus den Events rekonstruieren
# chat id -> chat data
chat_state: dict[str, dict[str, typing.Any]] = {}
# chat id -> message id -> message data
messages: dict[str, dict[str, dict[str, typing.Any]]] = {}

for event in events:
    match event["kind"]:
        case "chat":
            chat_id = event["chat"]["resource_id"]
            chat_state[chat_id] = event["chat"]
        case "message":
            chat_id = event["message"]["chat_id"]
            message_id = event["message"]["resource_id"]
            if chat_id not in messages:
                messages[chat_id] = {}
            messages[chat_id][message_id] = event["message"]
        case "state" | "keep_alive" | "tokens" | "file" | "error":
            pass  # ignore for now

# Rekonstruierten Zustand ausgeben
print(
    json.dumps(
        {
            "chats": chat_state,
            "messages": messages,
        },
        indent=2,
        ensure_ascii=False,
    )
)

Folgeanfragen senden ​

Um Folgeanfragen zu einem bestehenden Chat zu senden, verwenden Sie den Endpunkt POST /chats/{chat_id}/generate.

Die Antworten werden ebenfalls im SSE-Format zurückgegeben und können wie oben beschrieben verarbeitet werden.

python
import requests
import json

API_KEY = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"

chat_id = ""  # Hier ID des bestehenden Chats eintragen, der fortgesetzt werden soll
url = f"https://app.alan.de/api/v1/chats/{chat_id}/generate"

headers = {"accept": "application/json", "Content-Type": "application/json",  "Authorization": f"Bearer {API_KEY}"}

message_id = ""  # Hier ID der vorherigen Nachricht eintragen, auf die geantwortet werden soll
payload = json.dumps({
    "previous_message_id": message_id,
    "content": "Formuliere den LinkedIn Post weniger förmlich."
})

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)  # SSE-Event-Stream

Erweiterte Funktionen ​

Um die erweiterten Funktionen von Alan zu nutzen, können Sie der initialen Anfrage zusätzliche Parameter übergeben.

Die wichtigsten zusätzlichen Parameter werden im Folgenden beschrieben.

Einige Parameter können Sie alternativ auch in bestehenden Chats mittels des PUT-Chats-Endpunkts aktualisieren (siehe Swagger-Dokumentation). Die Aktualisierungen werden dann ab der nächsten Generierung berücksichtigt.

Wissensdatenbanken ​

Um Wissensdatenbanken zu nutzen, fügen Sie im Chat-Request die ID's der gewünschten Wissensdatenbank(en) hinzu.

python
import requests
import json

API_KEY = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"

url = "https://app.alan.de/api/v1/chats/"

headers = {"accept": "application/json", "Content-Type": "application/json",  "Authorization": f"Bearer {API_KEY}"}

knowledgebase_ids = [""]  # Hier ID's der gewünschten Wissensdatenbank(en) eintragen
payload = json.dumps({
    "content": "Welche Bedeutung hat die KI für den Wirtschaftsstandort Deutschland?",
    "settings": {
      "model": "comma-soft/comma-llm-agentic",
      "knowledgebase_ids": knowledgebase_ids
    }
})

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)  # SSE-Event-Stream

Dateien ​

Um mit Dateien zu chatten, müssen Sie zunächst die gewünschte(n) Datei(en) in Alan hochladen.

python
import requests
import json

API_KEY = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"

url = "https://app.alan.de/api/v1/files/"

headers = {"accept": "application/json", "Content-Type": "multipart/form-data",  "Authorization": f"Bearer {API_KEY}"}

file_path = ""  # Hier Dateipfad eintragen
with open(file_path, "rb") as f:
    file_content = f.read()
files = {"file": (file_path.name, file_content, "text/plain")}

response = requests.request("POST", url, headers=headers, files=files)

file_id = response.json()["resource_id"]

Sobald die Dateien hochgeladen und fertig verarbeitet sind (status_parsing ist gleich processed oder fallback), können Sie im Chat-Request die ID's der hochgeladenen Datei(en) hinzufügen.

Beachten Sie, dass die Dateien, die Sie hinzufügen, nicht mehr Text enthalten dürfen, als Alan auf einmal verarbeiten kann.

python
import requests
import json

API_KEY = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"

url = "https://app.alan.de/api/v1/chats/"

headers = {"accept": "application/json", "Content-Type": "application/json",  "Authorization": f"Bearer {API_KEY}"}

file_ids = [""]  # Hier ID's der gewünschten Datei(en) eintragen
payload = json.dumps({
    "content": "Fasse den angehängten Artikel über die Bedeutung der KI für den Wirtschaftsstandort Deutschland zusammen.",
    "settings": {
      "model": "comma-soft/comma-llm-agentic"
    },
    "attached_files": file_ids
})

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)  # SSE-Event-Stream

Experten ​

Um Experten zu nutzen, fügen Sie im Chat-Request die ID des gewünschten Experten hinzu.

Beachten Sie, dass der Experte so konfiguriert sein muss, dass das gewünschte Modell in dem Experten gesetzt ist.

Alle Parameter, die Sie im settings-Feld des Chat-Requests setzen, werden ignoriert, wenn ein Experte verwendet wird.

python
import requests
import json

API_KEY = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"

url = "https://app.alan.de/api/v1/chats/"

headers = {"accept": "application/json", "Content-Type": "application/json",  "Authorization": f"Bearer {API_KEY}"}

expert_id = ""  # Hier ID des gewünschten Experten eintragen
payload = json.dumps({
    "content": "Verfasse einen Beitrag über die Bedeutung der KI für den Wirtschaftsstandort Deutschland.",
    "expert_id": expert_id,
    "load_expert_instead_of_settings": True
})

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)  # SSE-Event-Stream

Fähigkeiten ​

Um Fähigkeiten zu nutzen, fügen Sie im Chat-Request die ID's der gewünschten Fähigkeit(en) hinzu.

Im settings-Feld des Chat-Requests können Sie den Parameter abilities_system füllen, um in Alan enthaltene Fähigkeiten zu verwenden. Die verfügbaren in Alan enthaltenen Fähigkeiten können Sie zuvor über den Endpunkt GET /abilities/system abrufen.

Um angebundene Fähigkeiten zu nutzen, füllen Sie im settings-Feld den Parameter abilities_mcp mit den ID's der gewünschten angebundenen Fähigkeit(en). Die verfügbaren angebundenen Fähigkeiten können Sie zuvor über den Endpunkt GET /abilities/mcp abrufen.

Um Chat-spezifisch das Genehmigungsverhalten für verwendete Fähigkeiten festzulegen, füllen Sie im settings-Feld den Parameter ability_approval_preferences.

Zum Beispiel können Sie die Internet-Fähigkeit mit automatischer Nutzungsgenehmigung folgendermaßen nutzen:

python
import requests
import json

API_KEY = ""  # Hier API-Schlüssel eintragen. Dieser beginnt mit "alan-"

url = "https://app.alan.de/api/v1/chats/"

headers = {"accept": "application/json", "Content-Type": "application/json",  "Authorization": f"Bearer {API_KEY}"}

payload = json.dumps({
    "content": "Welche aktuellen Nachrichten gibt es zur KI-Branche in Deutschland?",
    "settings": {
      "model": "comma-soft/comma-llm-agentic",
      "abilities_system": ["web"],
      "ability_approval_preferences": {
          "web": "auto"
      }
    }
})

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)  # SSE-Event-Stream

Copyright © 2023-2026 Comma Soft AG