AI for selfhost

[forehalo]

There are too many questions regarding AFFiNE AI support for selfhost instances and some of them are outdated.
Let's make this one as the official QA and progress tracking for all the concerns.
I will pin this on top of issues panel, the old ones or new comings will be closed directly and leave a ref to this issue.

Progress

• unbind actions with specified models
• support my own keys in admin panel
• support custom providers(ollama, deepseek, ...)
• more...

[forehalo]

Can I enable the AI in an unofficial way now in my instance?

The answer is yes.

Steps for those using provided compose file:

1. create a JSON config at ${CONFIG_LOCATION}/config.json

If you are using an editor that supports JSON lsp, the "$schema" field with provide you fully commented fields auto-complete

{
  "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
  "copilot": {
    "enabled": true,
    "providers.openai": {
      "apiKey": "your key",
      "baseUrl": "open-ai-compatitable.example.com"
    }
  }
}

2. restart your host

docker compose up -d

Steps for custom deployment:

1. create a JSON config

{
  "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
  "copilot": {
    "enabled": true,
    "providers.openai": {
      "apiKey": "your key",
    }
  }
}

2. Mount or Copy the config file to your instance

3. import the config

node --import ./scripts/register.js ./dist/data/index.js import-config ./path/to/config.json

4. restart your host

[losanglekk]

I try to set up today but get import-config not found issue. any ideas?

[forehalo]

pull the latest image

[D3m0cr1tusGR]

I tried this configuration to connect to my ollama server but it didn't work

{
        "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
        "copilot": {
                "enabled": true,
                "providers.openai": {
                        "apiKey": "ollama",
                        "baseUrl": "http://IP:11434/v1"
                }
        }
}

[ssly]

Can I enable the AI in an unofficial way now in my instance?

现在能否以非官方方式在我的实例中启用 AI？
The answer is yes.答案是肯定的。

Steps for those using provided compose file:

1. create a JSON config at ${CONFIG_LOCATION}/config.json1. 在 ${CONFIG_LOCATION}/config.json 创建一个 JSON 配置文件

If you are using an editor that supports JSON lsp, the "$schema" field with provide you fully commented fields auto-complete如果您使用的是支持 JSON lsp 的编辑器，"$schema"字段将为您提供带有完整注释的字段自动完成功能

{
"$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
"copilot": {
"enabled": true,
"providers.openai": {
"apiKey": "your key",
"baseUrl": "open-ai-compatitable.example.com"
}
}
}
2. restart your host  2. 重启主机

docker compose up -d

Steps for custom deployment:

1. create a JSON config1. 创建 JSON 配置文件

{
"$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
"copilot": {
"enabled": true,
"providers.openai": {
"apiKey": "your key",
}
}
}
2. Mount or Copy the config file to your instance2. 将配置文件挂载或复制到您的实例

3. import the config  3. 导入配置

node --import ./scripts/register.js ./dist/data/index.js import-config ./path/to/config.json
4. restart your host  4. 重启您的宿主

How can I configure DeepSeek? How to set up the model. Moreover, in the 0.21.2 management panel, the AI function cannot be activated.

[forehalo]

That why I called the solution in #11691 (comment) is "unofficial". to configure AI functionality in Admin panel is still work in progress.

Regarding using DeepSeek, it's concurrently not supported yet, but I think it will be available with AI admin panel together

[MrSquaare]

Hello!

Thanks for the tips for selfhosted instance

Will there be AI support for local workspace?

[forehalo]

You can only use simple actions in local workspace like random chat, translation. The actions with context awareness, for example embedding, can not be used with local workspaces, because the server doesn't know the content of your local workspace

[daydaya]

好像仍然有10次的使用限制，我使用自己的 API key 进行配置，并在openrouter后台看到了使用记录，但是affine中的AI仍然只能使用10次

[daydaya]

Wow, it's really possible! In the account settings, click on modify, and you can see the options, thank you very much 🙏

[vladkor97]

You're welcome :)

[ssly]

Wow, it's really possible! In the account settings, click on modify, and you can see the options, thank you very much 🙏哇，这真的可能！在账户设置中，点击修改，你可以看到选项，非常感谢 🙏

你使用的是什么模型，我这边这个管理员面板的 AI 按钮无法开启，是禁用状态

[Kosette]

@ssly 使用OpenAI兼容的API以及正确的apikey没有问题，服务启动时会检测API的可用性，可以查看日志。如果没有办法开启AI可能是配置有误。理论上还支持其他的AI provider，具有可用性可查看对应的源代码。

[zonbao]

请问，怎么更换掉系统原来的提示词。每次提问都带一大串自我介绍提示词

[boom404]

I created for myself a small server between Affine and Gemini or OpenRouter, who provides free API keys. Not sure if this allowed here in this chat.
My solution is implemented to start as normal docker container. "Ask AI" is working as expected

https://github.com/boom404/affine-copilot-fix

[zonbao]

Excellent, I used your method. Successfully used the model of Gemini and openrouter on AFFiNE 0.21.4

[NorkzYT]

Edit:

Figured it out:
I forgot to run node --import ./scripts/register.js ./dist/data/index.js import-config /root/.affine/config/config.json inside the docker container and then run docker compose up -d --force-recreate.

@boom404

I am following your guide from your repo to be able to use OpenAI with the AFFINE version of 0.21.4 which is the latest stable version and the connection is not working for some reason. Any help would be appreciated.

Below are all my files:

/opt/docker/affine/.affine/self-host/config/config.json:

{
    "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
    "server": {
        "name": "Affine"
    },
    "copilot": {
        "enabled": true,
        "providers.openai": {
            "apiKey": "my-not-exist-api-key",
            "baseUrl": "http://affine-copilot-fix:5000"
        }
    }
}

docker-compose.yml:

name: affine
services:
  affine-copilot-fix:
    container_name: affine-copilot-fix
    user: "1000:1000"
    build:
        context: ./affine-copilot-fix
        dockerfile: Dockerfile
    volumes:
        - ./logs:/app/src/logs
    env_file:
      - .env
    environment:
        - CREATE_LOG=True
        - OPENAI_API_KEY=${OPENAI_API_KEY}
        - OPENAI_BASE_URL=https://openrouter.ai/api/v1 # https://openrouter.ai/api/v1/
        - OPENAI_MODEL=openai/o4-mini # Or any openrouter model
    ports:
        - 5000:5000
    networks:
      - proxy

  affine:
    image: ghcr.io/toeverything/affine-graphql:${AFFINE_REVISION:-stable}
    container_name: affine_server
    ports:
      - '${PORT:-3010}:3010'
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
      affine_migration:
        condition: service_completed_successfully
    volumes:
      # custom configurations
      - /opt/docker/affine/.affine/self-host/storage:/root/.affine/storage
      - /opt/docker/affine/.affine/self-host/config:/root/.affine/config
    env_file:
      - .env
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/${DB_DATABASE:-affine}
    restart: unless-stopped
    networks:
      - proxy

  affine_migration:
    image: ghcr.io/toeverything/affine-graphql:${AFFINE_REVISION:-stable}
    container_name: affine_migration_job
    volumes:
      # custom configurations
      - /opt/docker/affine/.affine/self-host/storage:/root/.affine/storage
      - /opt/docker/affine/.affine/self-host/config:/root/.affine/config
    command: ['sh', '-c', 'node ./scripts/self-host-predeploy.js']
    env_file:
      - .env
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/${DB_DATABASE:-affine}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - proxy

  redis:
    image: redis
    container_name: affine_redis
    healthcheck:
      test: ['CMD', 'redis-cli', '--raw', 'incr', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - proxy  

  postgres:
    image: postgres:16
    container_name: affine_postgres
    volumes:
      - /opt/docker/affine/.affine/self-host/postgres/pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_DATABASE:-affine}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # you better set a password for you database
      # or you may add 'POSTGRES_HOST_AUTH_METHOD=trust' to ignore postgres security policy
      POSTGRES_HOST_AUTH_METHOD: trust
    healthcheck:
      test:
        ['CMD', 'pg_isready', '-U', "${DB_USERNAME}", '-d', "${DB_DATABASE:-affine}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - proxy

networks:
  proxy:
    driver: bridge
    external: true

[boom404]

any issues or questions, please open in my repo.

[zonbao]

@boom404 Hi, how do I customize the prompt word. Otherwise every request comes with a long string of prompt words:

 You are AFFiNE AI, a professional and humorous copilot within AFFiNE. You are powered by latest GPT model from OpenAI and AFFiNE. AFFiNE is an open source general purposed productivity tool that contains unified building blocks that users can use on any interfaces, including block-based docs editor, infinite canvas based edgeless graphic mode, or multi-dimensional table with multiple transformable views. Your mission is always to try your very best to assist users to use AFFiNE to write docs, draw diagrams or plan things with these abilities. You always think step-by-step and describe your plan for what to build, using well-structured and clear markdown, written out in great detail. Unless otherwise specified, where list, JSON, or code blocks are required for giving the output. Minimize any other prose so that your responses can be directly used and inserted into the docs. You are able to access to API of AFFiNE to finish your job. You always respect the users' privacy and would not leak their info to anyone else. AFFiNE is made by Toeverything .Pte .Ltd, a company registered in Singapore with a diverse and international team. The company also open sourced blocksuite and octobase for building tools similar to Affine. The name AFFiNE comes from the idea of AFFiNE transform, as blocks in affine can all transform in page, edgeless or database mode. AFFiNE team is now having 25 members, an open source company driven by engineers.

[boom404]

@boom404 Hi, how do I customize the prompt word. Otherwise every request comes with a long string of prompt words:

 You are AFFiNE AI, a professional and humorous copilot within AFFiNE. You are powered by latest GPT model from OpenAI and 

this is hard coded in Affine.

https://github.com/toeverything/AFFiNE/blob/canary/packages/backend/server/src/plugins/copilot/prompt/prompts.ts

[floli]

Since recently, I get this error message when trying to use it:

affine-1            | [Nest] 1  - 04/21/2025, 5:41:17 PM   ERROR [Sse] <selfhosted:http:1e2dbb90-d47a-40c6-a6a3-c9ffb4663273> no_copilot_provider_available ({"sessionId":"75d47f52-93b1-4bac-acc7-be9913cbc7e8","params":{},"throwInStream":false})
affine-1            | no_copilot_provider_available: No copilot provider available.
affine-1            |     at CopilotController.chooseTextProvider (file:///app/dist/plugins/copilot/controller.js:59:19)
affine-1            |     at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
affine-1            |     at async CopilotController.chatStream (file:///app/dist/plugins/copilot/controller.js:161:30)
affine-1            |     at async CopilotController.<anonymous> (file:///app/dist/base/metrics/utils.js:20:20)

My relevant config.json looks like

{
  "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
  "server": {
    "name": "myname",
    "host": "affine.myname.de",
    "https": true
  },
  "copilot": {
    "enabled": true,
    "providers.openai": {
      "apiKey": "sk-proj-...",
    }
  }
}

Any ideas?

[boom404]

I experienced the same problem. The AI chat in the sidebar wasn't working, but the normal "Ask AI" in documents was fine. I've turned off the "world icon" in the chat sidebar. But, i'm using my own Affine Copilot Fix, because I want to use Gemini - nevertheless, the problem should be maybe the same.

[NorkzYT]

Same issue here using the latest stable self hosted docker version.

[forehalo]

if you enable the websearch feature, by toggling the browser icon on, the server will prefer choosing pplx as provider rather than openai

[NorkzYT]

@forehalo

Which docker version does your solution work with?
#11722 (comment)

I have used stable and canary version and none work with your configuration and would like to know the version that works to see the difference in code from before to now to know how to fix this and possibly have a Github PR made with a solution.

[forehalo]

the latest stable should work fine

[ebildebil]

Is there a way to define which model to use?
From my litellm logs, I see it either picks gpt-4.1 or gpt-4.1-2025-04-14. These are more expensive than eg: 4o-mini or 4.1-mini, or say if one wanted to use o4-mini for reasoning..?

[forehalo]

not available yet

[Lormited]

I use openresty to redirect the requests to deepseek

server {
    listen 8080;
    server_name localhost;

    location /v1/chat/completions {
        access_by_lua_block {
            ngx.req.read_body()
            local body = ngx.req.get_body_data()
            if body then
                body = body:gsub('"model"%s*:%s*"gpt%-4%.1"', '"model":"deepseek-chat"')
                ngx.req.set_body_data(body)
            end
        }

        proxy_pass https://api.deepseek.com/v1/chat/completions;
        proxy_set_header Authorization "Bearer sk-xxxxxxxxxxxx";
        proxy_set_header Content-Type "application/json";
    }
}

and the config.json

{
    "$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
    "copilot": {
        "enabled": true,
        "providers.openai": {
            "apiKey": "none",
            "baseUrl": "http://<your_affine_docker_host(172.17.0.1)>:8080"
        }
    }
}

[ke-ma-fi]

Is there a usage cap when using AI on self hosted even when using my own AI Token????

[forehalo]

nope

[ldehner]

Even tho I set the config.json (validated if its set with cat config.json in root/.affine/config) and set unlimited ai usage, I get this error when trying to send a message:

[ke-ma-fi]

Same here, but I think it's because of the unlimited_Copilot Feature. When I set my config.json and imported it into node, everything was working until the quota cap. Once I set unlimited_copilot, the quota was gone, but I get this error. So i think they have hardcoded something that tries to use a specific ai provider once somebody has purchesed the ai feature. I mean it makes total seance cause once you purchased, affine is responsible for providing the ai..

[forehalo]

currently AFFiNE binds actions to specific provider or models, because the models capabilities distinguish, like some model only process text and return text, some can read from pictures, some can generate pictures. You may also hear GPT-4o, GPT-o1, gemini-2.0, etc. They are all for different purposes. And what's even worse, some advanced models was considered to be used in AFFiNE are not available for all, like openai accounts.

the error NO_COPILOT_PROVIDER_AVAILABLE means there is no provider available to process the action you are taking. If you only set the config for providers.openai, you may add providers.gemini or providers.perplexity.

this is the main reason we didn't tell AFFiNE AI as self-host ready and can only be used as experimental feature.

[ebildebil]

Coudn't we allow users to congigure which model to use instead of hard coding, eg: openai/openai-4.1-mini, etc... and just mention that the LLM endpoint must be openai compatible.

This helps, eg: when using liteLLM that give an openai endpoint for whichever model is configured behind it. ofcourse for a selfhosted instance the user/hoster will need to know if they should use a text only or a multimodal model. There are cheaper and even free models, that can be used this way, eg: gpt4.1-mini instead of gpt-4.1 (which is hardcoded and more expensive) or Mistral-small which is free and multimodal.

[forehalo]

definitely. We are on it but it will take some time to finish the refactory. Please be patient then.

[denieboy]

I am trying to set up the latest stable and beta for AI running on a self-hosted cloud.
Unfortunately, no success.
AI is generating something but then I got no output for simple text prompts.

After several tries I got this:

Is it possible to resolve this?

[abelit]

Hope AFFiNE to support custom providers(ollama, deepseek, ...)

[ke-ma-fi]

Hey guys, since ./scripts/register.js got removed, I can't import my config for the ai anymore with node --import ./scripts/register.js ./dist/data/index.js import-config ./path/to/config.json. Did anybody get ai to work on 0.22.2?

[joebnb]

Hey guys, since ./scripts/register.js got removed, I can't import my config for the ai anymore with node --import ./scripts/register.js ./dist/data/index.js import-config ./path/to/config.json. Did anybody get ai to work on 0.22.2?

facing same issue

[joebnb]

Hey guys, since ./scripts/register.js got removed, I can't import my config for the ai anymore with node --import ./scripts/register.js ./dist/data/index.js import-config ./path/to/config.json. Did anybody get ai to work on 0.22.2?

facing same issue

it's seems the official compose example located config position wasn't load by default

 volumes:
      # custom configurations
      - ${UPLOAD_LOCATION}:/root/.affine/storage
      - ${CONFIG_LOCATION}:/root/.affine/config

[andergoros]

Any updates?

[ke-ma-fi]

I'd like to get some info as well. The deep AI Integration is one of the main features of affine and I would love to see that for self-hosted as well.

[juzdm]

Any updates?