Hướng dẫn sử dụng

Cài đặt, thiết lập và vận hành Proxyma: tìm kiếm và một tác nhân (agent) AI trên chính tài liệu và hệ thống của bạn, chạy trên máy tính hoặc máy chủ của bạn.

Community và Enterprise

• Tìm kiếm, trò chuyện, tác nhân, rào chắn, đồ thị tri thức, MCP và HTTP API có ở cả hai gói.
• Bạn tự cung cấp mô hình AI. Mô hình chạy cục bộ không tốn gì ngoài phần cứng của bạn; nhà cung cấp trực tuyến tính tiền trực tiếp với bạn.

Cài đặt

Desktop trên Windows Community

1. Tải proxyma-x64-v<version>.exe từ trang tải về.
2. Chạy tệp đó. Trình cài đặt hiển thị giấy phép (GNU AGPL v3); chọn Next.
3. Khởi động Proxyma từ trình đơn Start khi đang có mạng. Lần khởi động đầu tiên tải về phần còn lại của Proxyma, khoảng 650 MB, rồi thiết lập môi trường Python (khoảng một phút).
4. Proxyma mở ra trong cửa sổ riêng. Các lần khởi động sau không cần internet.

• Việc tải về bị gián đoạn sẽ được tiếp tục ở lần khởi động sau.
• Mọi tệp đều được đối chiếu với mã kiểm tra đã ký của bản phát hành trước khi cài đặt.
• Sau proxy của công ty, Proxyma dùng thiết lập proxy của Windows hoặc HTTPS_PROXY, cùng các tổ chức cấp chứng chỉ mà Windows tin cậy.
• Nếu SmartScreen cảnh báo ở lần chạy đầu, hãy kiểm tra tệp đến từ trang tải về, rồi chọn More info → Run anyway.

Đóng cửa sổ không thoát Proxyma; nó vẫn chạy ở khay hệ thống.

• Mở lại: nhấp đúp vào biểu tượng ở khay hệ thống, hoặc nhấp chuột phải rồi chọn Open Proxyma. Open in Browser mở nó trong một thẻ trình duyệt.
• Thoát: menu ở góc trên bên phải, hoặc menu của biểu tượng ở khay, → Thoát Proxyma.
• Không thấy biểu tượng? Bấm vào ^ cạnh đồng hồ.

Proxyma chỉ lắng nghe trên 127.0.0.1:4246. Trình duyệt mà bạn tự mở tới địa chỉ đó sẽ hỏi mã truy cập, nằm trong %LOCALAPPDATA%\proxyma\access-code. Cửa sổ ứng dụng và khay hệ thống tự đăng nhập cho bạn.

Desktop trên Ubuntu và Debian Community

Cần Ubuntu hoặc Debian, bản 64-bit (x86-64), có phiên làm việc đồ họa X11 hoặc Wayland, cùng bộ nhớ và dung lượng đĩa như trên Windows. Với máy không có màn hình, hãy dùng Home Server.

Từ kho APT của Proxyma (khuyến nghị):

sudo install -d -m 0755 /etc/apt/keyrings
sudo wget -qO /etc/apt/keyrings/proxyma.asc https://proxyma.ai/keys/proxyma-release.asc
echo "deb [signed-by=/etc/apt/keyrings/proxyma.asc] https://github.com/proxyma-ai/proxyma-releases/releases/download/apt/ ./" | sudo tee /etc/apt/sources.list.d/proxyma.list
sudo apt update && sudo apt install proxyma

• Dấu vân tay của khóa là BE3A B092 AB25 4FA4 5C57 8AF4 F571 F889 94F6 B817.
• Từ tệp đã tải về: sudo apt install ./proxyma_<version>_amd64.deb (giữ nguyên ./).
• Khởi động Proxyma từ trình đơn ứng dụng khi đang có mạng. Lần khởi động đầu tiên tải phần còn lại của ứng dụng và thiết lập Python, như trên Windows.
• Khởi động lại khi nó đang chạy sẽ đưa cửa sổ của nó trở lại.
• Thoát: menu ở góc trên bên phải → Thoát Proxyma. Đóng cửa sổ không thoát ứng dụng. GNOME không có tiện ích mở rộng và phiên Wayland thuần không hiển thị biểu tượng ở khay.
• Chạy proxyma trong cửa sổ dòng lệnh để xem thông báo khởi động; đóng cửa sổ đó sẽ dừng ứng dụng.
• Mã truy cập nằm trong ~/.local/share/proxyma/access-code.

Home Server trên Docker Community

Ứng dụng một người dùng trong một container, cho máy chủ gia đình, NAS hoặc VPS nhỏ, dùng từ trình duyệt ở một máy khác trong mạng của bạn.

curl -LO https://github.com/proxyma-ai/proxyma-releases/releases/download/v<version>/proxyma-homeserver-<version>-compose.tar.gz
tar -xzf proxyma-homeserver-<version>-compose.tar.gz
cd proxyma-homeserver-<version>
./install.sh

1. Lần chạy đầu tiên tạo tệp .env rồi dừng. Hãy đặt ai được truy cập (bên dưới).
2. Chạy lại ./install.sh. Nó khởi động Proxyma và in ra mã truy cập.
3. Mở Proxyma trong trình duyệt và nhập mã truy cập.

• Chạy lại ./install.sh sau mỗi lần thay đổi .env.
• Mã được in ra ở mỗi lần khởi động và lưu trong ./data/.local/share/proxyma/access-code. Để tự chọn mã, đặt PROXYMA_ACCESS_CODE (ít nhất 16 ký tự); khi đó nhật ký chỉ nêu tên thiết lập này thay vì in mã.
• Profile office (bật mặc định) cho phép tác nhân tạo và sửa tệp Office. Container của nó được dựng trên máy chủ và cần internet một lần; bỏ office khỏi COMPOSE_PROFILES trên máy không có internet.
• Không dùng tập lệnh cài đặt: docker compose -f compose.community.yaml up -d, rồi đọc mã bằng docker compose -f compose.community.yaml logs proxyma | grep -A1 -i "access code".

Ai được truy cập

• Ai có mã truy cập thì có mọi tài liệu bạn lập chỉ mục, mọi cuộc trò chuyện và chi phí AI của bạn. Hãy giữ nó như một mật khẩu.
• Từ bên ngoài nhà, hãy dùng đường hầm (Tailscale, WireGuard, hoặc ssh -L 4246:localhost:4246), và thêm tên bạn gõ vào PROXYMA_ALLOWED_HOSTS (không cần với ssh -L).
• Sau một reverse proxy công khai, đặt PROXYMA_ALLOWED_HOSTS là tên miền của bạn. * trả lời mọi tên máy; chỉ dùng khi đã có thứ khác đứng trước Proxyma quyết định ai được đi qua.

Enterprise Server trên Docker Compose Enterprise

curl -LO https://github.com/proxyma-ai/proxyma-releases/releases/download/v<version>/proxyma-enterprise-server-<version>-compose.tar.gz
tar -xzf proxyma-enterprise-server-<version>-compose.tar.gz
cd proxyma-enterprise-server-<version>
./install.sh

1. Lần chạy đầu tiên tạo .env rồi dừng. Đặt ít nhất COMPOSE_PROFILES, PUBLIC_ORIGIN và, với profile tls, PROXYMA_HOST.
2. Chạy lại ./install.sh. Nó tạo khóa ký phiên đăng nhập trong keys/, mật khẩu cho cơ sở dữ liệu đi kèm, tải image, khởi động hệ thống và chờ tới khi Proxyma trả lời.
3. Mở /setup và tạo quản trị viên đầu tiên bằng setup token trong nhật ký: docker compose logs proxyma-server | grep "setup token". Khởi động lại trước khi thiết lập sẽ in ra token mới.

• Luôn khởi động bằng ./install.sh: thiếu khóa của nó, máy chủ dừng với lỗi Failed to load JWT keys. Nó không bao giờ ghi đè giá trị bạn đã đặt, không tạo khóa mới và không xóa dữ liệu.
• Để cố định phiên bản, đặt PROXYMA_IMAGE=ghcr.io/proxyma-ai/proxyma-enterprise-server:<version>.
• Chỉ dùng image, không có tập lệnh cài đặt: tệp compose.enterprise.yaml trong gói (Docker Compose 2.20.2 trở lên). Ghi PROXYMA_DB_PASSWORD=... vào .env, chạy docker compose -f compose.enterprise.yaml up -d, và đọc setup token trong nhật ký. Cơ sở dữ liệu đi kèm của tệp này không sao lưu liên tục.

Giá trị có sẵn là postgres,tls,office. Bỏ đi những gì máy chủ của bạn đã có. Khi không có profile nào, Proxyma chạy trong một container duy nhất.

PostgreSQL của riêng bạn

CREATE DATABASE proxyma OWNER proxyma;
\c proxyma
CREATE EXTENSION IF NOT EXISTS vector;

• Đặt PROXYMA_DB_URL, PROXYMA_DB_USER và PROXYMA_DB_PASSWORD, và bỏ postgres khỏi COMPOSE_PROFILES.
• Nếu CREATE EXTENSION thất bại, máy chủ đó chưa cài pgvector. Các dịch vụ được quản lý (Amazon RDS, Google Cloud SQL, Azure Database) bật nó cho từng instance.
• Proxyma tự tạo các bảng của mình khi khởi động.

Reverse proxy của riêng bạn

Bỏ tls khỏi COMPOSE_PROFILES và chuyển tiếp tới 127.0.0.1:4246. Proxy phải chuyển các header Host, X-Forwarded-For và X-Forwarded-Proto, không được đệm phản hồi (câu trả lời được truyền dần), và cần thời gian chờ đọc dài. nginx:

location / {
    proxy_pass http://127.0.0.1:4246;
    proxy_http_version 1.1;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 3600s;
    client_max_body_size 200M;
}

Caddy:

proxyma.example.com {
	reverse_proxy 127.0.0.1:4246 {
		flush_interval -1
		transport http {
			read_timeout 3600s
		}
	}
	request_body {
		max_size 200MB
	}
}

Traefik tự chuyển các header và mặc định không đệm phản hồi; nó chỉ cần router và loadbalancer.server.port=4246.

Không truy cập được registry

docker pull ghcr.io/proxyma-ai/proxyma-enterprise-server:<version>
docker save ghcr.io/proxyma-ai/proxyma-enterprise-server:<version> | gzip > proxyma-enterprise-server.tar.gz
# on the server:
docker load < proxyma-enterprise-server.tar.gz

Đặt PROXYMA_IMAGE là tag đó và chạy ./install.sh. Các profile postgres, tls và office tải image riêng của chúng, nên máy chủ không có registry dùng COMPOSE_PROFILES= cùng cơ sở dữ liệu và proxy của riêng mình.

Trên Kubernetes

Hai Helm chart, đính kèm mỗi bản phát hành: proxyma-enterprise-<version>.tgz Enterprise và proxyma-community-<version>.tgz (Home Server) Community, mỗi chart kèm bản manifest thuần (proxyma-<edition>-<version>.yaml). Chúng cần Kubernetes 1.27 trở lên.

helm install proxyma-enterprise https://github.com/proxyma-ai/proxyma-releases/releases/download/v<version>/proxyma-enterprise-<version>.tgz -n proxyma --create-namespace
kubectl -n proxyma logs statefulset/proxyma-enterprise | grep -i "setup token"
kubectl -n proxyma port-forward svc/proxyma-enterprise 4246:4246

Sau đó mở http://localhost:4246/setup. Với Community, dùng proxyma-community và đọc mã truy cập bằng kubectl -n proxyma logs statefulset/proxyma-community | grep -A1 -i "access code".

• Một bản sao (replica). Mỗi lần nâng cấp gián đoạn một hai phút.
• Chỉ dùng block storage (ReadWriteOnce); không dùng NFS, EFS, SMB hay Azure Files. persistence.size mặc định là 20Gi.
• Cố định image bằng image.digest hoặc image.tag.
• Địa chỉ: đặt config.publicUrl và bật ingress. Cấu hình sẵn cho nginx tắt việc đệm phản hồi và cho phép tải lên 200 MB.
• Cơ sở dữ liệu: postgresql.enabled chạy PostgreSQL 16 có pgvector (không sao lưu liên tục); hoặc đặt externalDatabase.*.
• Secret: secrets.existingSecret chứa credential-key, setup-token, license-activation-key, sandbox-token và db-password (Community: access-code, credential-key, sandbox-token). Dùng nó với Argo CD hoặc Flux.
• Dùng thử: license.trialEnabled (bật mặc định); license.clusterId mặc định là uid của namespace kube-system.
• Đăng nhập một lần: truyền các biến của nó (xem Đăng nhập một lần) qua config.extraEnv.
• Probe: /api/v1/health/live và /api/v1/health/ready.
• Manifest thuần: kubectl apply -n <namespace> -f proxyma-community-<version>.yaml. Enterprise cần tạo Secret cho cơ sở dữ liệu trước: kubectl -n <namespace> create secret generic proxyma-postgresql --from-literal=password="$(openssl rand -hex 24)".
• Nâng cấp bằng cách tiến lên phiên bản chart mới; helm rollback không hoàn tác được thay đổi cơ sở dữ liệu.
• Sao lưu volume dữ liệu, cơ sở dữ liệu và Secret chứa credential key.

Dùng thử và giấy phép Enterprise Enterprise

• Bản dùng thử tự bắt đầu. Ở lần khởi động đầu tiên, Enterprise Server có internet sẽ xin máy chủ giấy phép của Proxyma 30 ngày dùng thử mọi tính năng Enterprise. Không cần thẻ, không cần biểu mẫu.
• Một lần cho mỗi bản triển khai. Cài lại trong 30 ngày đó vẫn nhận lại bản dùng thử cũ; sau đó, bản triển khai đã dùng hết lượt thử.
• Những gì được gửi đi: một mã định danh ngẫu nhiên của bản triển khai, cùng mã băm một chiều của machine id trên máy chủ và của cluster id. Không có gì về tài liệu hay con người của bạn.
• Trước khi bản dùng thử bắt đầu (hoặc khi không có giấy phép), máy chủ có một tài khoản, là quản trị viên đầu tiên, và không có Microsoft 365.
• Cài đặt → Giấy phép (Quản trị viên cấp cao) cho biết gói, số ngày còn lại và mã triển khai.

Máy chủ không có internet

1. Đặt PROXYMA_LICENSE_TRIAL_ENABLED=false (Helm: license.trialEnabled: false).
2. Trong Cài đặt → Giấy phép, chọn Sao chép mã triển khai.
3. Trên bất kỳ máy nào có kết nối, mở proxyma.ai/enterprise/trial, dán mã và chọn Nhận khóa dùng thử.
4. Quay lại máy chủ, chọn Kích hoạt giấy phép, dán khóa và chọn Kích hoạt. Khóa được kiểm tra ngay trên máy chủ, không cần mạng, và chỉ dùng được cho bản triển khai đó.

Giấy phép

• Mua trên trang bảng giá; khóa giấy phép được gửi qua email. Để nhận báo giá, gửi thư tới contact@proxyma.ai.
• Kích hoạt trong Cài đặt → Giấy phép → Kích hoạt giấy phép. Khóa giấy phép được kích hoạt trực tuyến, một lần; giấy phép đã ký cấp cho mã triển khai của bạn được kiểm tra ngoại tuyến.
• Proxyma xác nhận giấy phép vài giờ một lần. Nếu không liên lạc được máy chủ giấy phép, không có gì thay đổi; sau một thời gian sẽ có biểu ngữ nhắc.
• Giải phóng giấy phép này trả giấy phép lại để dùng cho bản triển khai khác.

Khi bản dùng thử hoặc giấy phép hết hạn

Máy chủ vẫn hoạt động và ngừng mở rộng:

• Mọi người vẫn đăng nhập được, bằng mật khẩu và bằng đăng nhập một lần. Tìm kiếm, trò chuyện và mọi nguồn dữ liệu vẫn chạy.
• Tài khoản mới phải chờ có giấy phép.
• Nguồn Microsoft 365 vẫn được liệt kê và tìm kiếm được, nhưng ngừng đồng bộ.
• Khách hàng trọng điểm chuyển sang chỉ đọc, và các công cụ khách hàng trọng điểm của tác nhân không còn được cung cấp.
• Giới hạn chi tiêu vẫn có hiệu lực, và nhật ký vẫn tiếp tục ghi.
• Mọi người thấy biểu ngữ trong 7 ngày cuối của bản dùng thử.

Lần chạy đầu tiên

1. Thêm một nhà cung cấp AI trong Cài đặt → Nhà cung cấp AI. Không có gì hoạt động cho tới khi có một nhà cung cấp liên hệ được. Trang này liệt kê những gì còn phải chọn.
2. Chọn mô hình: mô hình trò chuyện trong Cài đặt → Tác nhân, mô hình vector nhúng trong Cài đặt → Tìm kiếm.
3. Thêm một nguồn dữ liệu trong Nguồn dữ liệu → Kết nối. Hãy bắt đầu nhỏ.
4. Đặt một câu hỏi. Câu trả lời trích dẫn tài liệu của bạn nghĩa là việc thiết lập đã hoàn tất.

Enterprise Thiết lập nhà cung cấp AI và mô hình thuộc về quản trị viên; Quản trị viên cấp cao thay đổi chúng. Sau đó thêm mọi người trong Quản trị → Người dùng, hoặc để họ đăng nhập một lần (SSO).

Nhà cung cấp AI

• Giao thức: OpenAI, Anthropic, Google Gemini, Azure OpenAI, Ollama, OpenRouter, LiteLLM, và OpenAI-compatible cho mọi máy chủ nói API của OpenAI (DeepSeek, Mistral, Groq, Together, vLLM, LM Studio có sẵn làm điểm xuất phát).
• Hoàn toàn cục bộ: cài Ollama và dùng http://127.0.0.1:11434. Không có văn bản tài liệu nào tới nhà cung cấp. Câu trả lời sẽ chậm hơn và kém hơn so với mô hình trực tuyến.
• Trực tuyến: câu hỏi của bạn và các đoạn văn tác nhân đọc được gửi tới nhà cung cấp đó, theo tài khoản của bạn và điều khoản của họ. Với tài liệu mật, hãy dùng mô hình cục bộ.
• Đổi mô hình vector nhúng nghĩa là phải lập chỉ mục lại toàn bộ trước khi tìm kiếm đáng tin cậy trở lại.
• Dịch vụ AI của công ty dùng chứng chỉ riêng: xem Xử lý sự cố.

Chi phí

• Chi phí được ước tính theo đơn giá bạn đặt cho từng nhà cung cấp, không lấy từ hóa đơn của nhà cung cấp. Mô hình chưa có đơn giá được tính là 0 USD và được đánh dấu.
• Nhật ký → Lần gọi LLM liệt kê mọi lần gọi mô hình kèm số token và chi phí.
• Community Giới hạn chi tiêu hằng tháng nằm trong Cài đặt → Mức sử dụng & Chi phí.
• Enterprise Quản trị → Mức sử dụng & chi phí cho thấy chi phí theo dịch vụ, nhà cung cấp, mô hình và người dùng. Các giới hạn nằm ở Giới hạn chi tiêu.

Nguồn dữ liệu

Nguồn dữ liệu là thứ Proxyma lập chỉ mục: một thư mục, một trang web, một dự án Jira, một kênh Slack. Phần lớn nguồn đọc qua một kết nối: địa chỉ và thông tin đăng nhập của một tài khoản trên một dịch vụ.

1. Thêm kết nối trong Cài đặt → Kết nối → Thêm kết nối, rồi chọn Kiểm tra.
2. Thêm nguồn trong Nguồn dữ liệu → Kết nối, chọn kết nối, rồi điền những gì cần đọc.

• Thêm một kết nối cho mỗi máy chủ hoặc tài khoản. Kết nối đầu tiên của mỗi loại là mặc định; hộp thoại cấu hình của nguồn cho phép chuyển nó sang kết nối khác.
• Proxyma chỉ đọc, và không bao giờ thay đổi gì ở nguồn. Chỉ kết nối Jira, Confluence và Bitbucket (Data Center hoặc Server) mới có thể được cấp quyền Ghi, cho tác nhân (xem Tác nhân).
• Thông tin đăng nhập đã lưu được mã hóa.
• Enterprise Kết nối là của riêng từng người. Một nguồn là riêng tư với người đã thêm nó cho tới khi họ chia sẻ; chia sẻ cho phép đồng nghiệp tìm kiếm những gì nó đã lập chỉ mục. Một số loại không bao giờ chia sẻ được (bên dưới), vì chúng được đọc bằng quyền truy cập của một người.
• Enterprise Với dịch vụ đăng nhập bằng OAuth, quản trị viên thiết lập ứng dụng một lần cho mọi người, và mỗi người chỉ cần đăng nhập.

Mọi loại nguồn dữ liệu

Với kết nối đăng nhập được bằng OAuth, hãy đăng ký một ứng dụng ở dịch vụ, đặt địa chỉ chuyển hướng của nó là địa chỉ mà hộp thoại kết nối hiển thị (địa chỉ bạn mở Proxyma, theo sau là /api/v1/connections/oauth/callback), dán client ID và secret của nó vào kết nối, lưu lại, rồi chọn Đăng nhập. Chỉ xin quyền đọc.

Tệp tin

• Community Desktop: Thư mục trên máy, rồi chọn một thư mục. Nó được lập chỉ mục tại chỗ, không bao giờ bị sao chép hay thay đổi. Bao gồm cả thư mục con tắt cho tới khi bạn bật.
• Home Server và Enterprise Server: Tải tệp tin lên, rồi kéo thả tệp hoặc cả thư mục, tối đa 200 MB mỗi tệp. Proxyma giữ bản sao riêng, và xóa nguồn sẽ xóa bản sao đó.
• Chọn các loại tệp cần lập chỉ mục khi thêm nguồn, hoặc sau này trong hộp thoại cấu hình.

Trang web

• Nhập URL bắt đầu và một tên.
• Độ sâu thu thập: mặc định 3 lớp liên kết, tối đa 50. Số trang tối đa: mặc định 100, tối đa 20.000.
• Chỉ ở trong cùng một tên miền bật theo mặc định. Kết xuất JavaScript đọc các trang được dựng trong trình duyệt.
• Để thu hẹp phạm vi thu thập, mở hộp thoại cấu hình của nguồn và đặt Chỉ đi theo các URL khớp với.

Thư mục chia sẻ mạng

1. Thêm một kết nối Thư mục chia sẻ mạng: máy chủ tệp, cùng tên người dùng miền và mật khẩu của bạn.
2. Trong Nguồn dữ liệu → Kết nối, chọn Thư mục chia sẻ mạng và nhập đường dẫn, ví dụ \\fileserver\share\folder.

• Tệp được đọc bằng tài khoản của bạn, nên chỉ những gì bạn mở được mới được lập chỉ mục, và chỉ trên máy chủ đó.
• Mật khẩu bị máy chủ từ chối sẽ không được thử lại cho tới khi bạn đổi nó.
• Enterprise Quản trị viên cấp cao có thể liệt kê các máy chủ tệp được phép dùng, trong Cài đặt → Mạng → Máy chủ tệp tin được phép.

Jira, Confluence và Bitbucket

Jira

• Cloud: tạo API token tại id.atlassian.com (Security → API tokens). Trong kết nối, chọn Email và API token (Cloud) và nhập https://your-site.atlassian.net, email của bạn và token. Một token dùng được cho cả Jira và Confluence; nó hết hạn vào ngày bạn chọn.
• Data Center hoặc Server: tạo personal access token trong hồ sơ Jira của bạn, rồi nhập địa chỉ máy chủ (kèm đường dẫn) và token.
• Nguồn: mã dự án, PROJ trong PROJ-123. Mỗi issue là một tài liệu: các trường, mô tả, liên kết, issue con, bình luận và lịch sử thay đổi.

Confluence

• Kết nối giống như Jira. Trên Data Center hoặc Server, tạo personal access token trong ảnh hồ sơ → Settings → Personal Access Tokens.
• Nguồn: mã không gian, TEAM trong /spaces/TEAM/ hoặc /display/TEAM/. Mỗi trang hiện hành là một tài liệu, kèm nhãn, vị trí trong cây trang, tác giả và bình luận. Bài blog và tệp đính kèm không được lập chỉ mục.

Bitbucket (Data Center hoặc Server)

• Tạo một HTTP access token trong Bitbucket, rồi nhập địa chỉ máy chủ và token.
• Nguồn: mã dự án và slug của kho mã.

Bitbucket Cloud

• Email và API token: tại id.atlassian.com chọn Create API token with scopes, ứng dụng Bitbucket, với read:repository:bitbucket, read:pullrequest:bitbucket và read:user:bitbucket.
• Access token: access token của workspace, dự án hoặc kho mã với Repositories: Read và Pull requests: Read.
• Nguồn: workspace/repository. Pull request bật mặc định; Tệp tài liệu (tệp Markdown và văn bản tới 1 MB trên nhánh chính) tắt. Mã nguồn không được lập chỉ mục.

Jira, Confluence và Bitbucket đồng bộ mỗi giờ, chỉ đọc những gì đã thay đổi, và gỡ các mục đã xóa mỗi ngày một lần.

GitHub, GitLab và SVN

GitHub

• Tạo classic token với scope repo, hoặc fine-grained token đọc được issue, pull request và nội dung. Với GitHub Enterprise Server, đặt URL API là https://your-host/api/v3.
• Nguồn: owner/repository. Issue và Pull request bật; Tệp tài liệu trên nhánh mặc định tắt. Mã nguồn không được lập chỉ mục. Đồng bộ mỗi giờ.

GitLab

• Tạo personal, group hoặc project access token chỉ với scope read_api (token của group và project dùng vai trò Reporter). Với GitLab tự quản lý, đặt URL GitLab.
• Hoặc đăng nhập bằng OAuth trên gitlab.com: một application với scope read_api, đánh dấu Confidential.
• Nguồn: đường dẫn dự án (acme/website) hoặc một nhóm (acme, kèm các nhóm con). Issue và merge request bật; tệp tài liệu tắt. Mã nguồn không được lập chỉ mục.

SVN

• Kết nối nhận URL gốc của kho, tên người dùng và mật khẩu của bạn. Trên máy chủ VisualSVN dùng xác thực Windows, tên người dùng có kèm tên miền.
• Nguồn: đường dẫn kho mã. Chọn các loại tệp; Bao gồm cả thư mục con bật theo mặc định.

Quản lý công việc

Linear

• Tạo personal API key với quyền Read trong Settings → Security & access, hoặc đăng nhập bằng một OAuth application.
• Nguồn: mã nhóm như ENG, OPS; để trống sẽ đọc mọi nhóm.

Asana

• Tạo personal access token trong developer console (My apps), hoặc đăng nhập bằng một ứng dụng có các scope đọc workspaces:read, projects:read, project_sections:read, tasks:read, stories:read, users:read, custom_fields:read và tags:read.
• Nguồn: workspace, và ID hoặc tên dự án; để trống sẽ đọc mọi dự án bạn thấy.

monday.com

• Sao chép personal API token (ảnh hồ sơ → Developers → API token), hoặc đăng nhập bằng một ứng dụng có me:read, account:read, boards:read, updates:read và users:read.
• Nguồn: ID hoặc liên kết bảng; để trống sẽ đọc mọi bảng bạn thấy. Đồng bộ hai giờ một lần. Gói Free, Basic và Standard cho phép 1.000 lần gọi API mỗi ngày; việc đồng bộ tiếp tục sau nửa đêm UTC.

Trello

• Tạo một Power-Up tại trello.com/power-ups/admin, tạo API key của nó, rồi theo liên kết Token bên cạnh để lấy token. Dán cả hai.
• Nguồn: liên kết hoặc ID bảng; để trống sẽ đọc mọi bảng đang mở mà bạn tham gia.

ClickUp

• Tạo personal API token (pk_...) trong Settings → Apps, hoặc đăng nhập bằng một ứng dụng ClickUp.
• Nguồn: workspace, và tùy chọn ID của space, folder và list.

Airtable

• Tạo token tại airtable.com/create/tokens với data.records:read và schema.bases:read (và user.email:read cho nút Kiểm tra), có quyền truy cập từng base. Hoặc đăng nhập bằng một OAuth integration với cùng các scope.
• Nguồn: base (ID hoặc liên kết), và tùy chọn một bảng và một view. Tệp đính kèm được liệt kê theo tên; nội dung của chúng không được lập chỉ mục.

Notion và Slack

Notion

1. Tại notion.so/profile/integrations, tạo một integration Internal chỉ với Read content, và sao chép secret của nó (ntn_...).
2. Trong Notion, chia sẻ từng trang hoặc cơ sở dữ liệu với nó (... → Connections). Chia sẻ một trang là chia sẻ cả các trang bên dưới.
3. Nguồn: liên kết trang hoặc cơ sở dữ liệu, mỗi dòng một liên kết; để trống sẽ đọc mọi thứ được chia sẻ với integration.

Slack

1. Tại api.slack.com/apps, chọn Create New App → From a manifest, với các bot scope: channels:history, channels:read, groups:history, groups:read, users:read. Không có scope nào cho tin nhắn riêng.
2. Install to Workspace, sao chép Bot User OAuth Token (xoxb-...) và dán vào kết nối.
3. Mời ứng dụng vào từng kênh: /invite @Proxyma.
4. Nguồn: các kênh dạng #name hoặc ID (để trống: mọi kênh công khai có ứng dụng), và số ngày lịch sử.

• Đăng nhập bằng Slack cũng dùng được, nhưng chỉ trên địa chỉ https://.
• Mỗi chuỗi trả lời là một tài liệu; tin nhắn ngoài chuỗi được gộp thành một tài liệu cho mỗi kênh mỗi ngày.
• Hãy đọc điều khoản API của Slack và chính sách của workspace trước khi lập chỉ mục.

Google: Drive, Gmail và Calendar

Một kết nối Google phục vụ cả ba, với quyền chỉ đọc. Bạn cần một dự án Google Cloud đã bật Drive, Gmail và Calendar API (chỉ những API bạn dùng).

• Đăng nhập bằng Google: cấu hình OAuth consent screen (Internal cho tổ chức Workspace, ngược lại là External) với các scope drive.readonly, gmail.readonly và calendar.readonly. Tạo OAuth client ID loại Web application với địa chỉ chuyển hướng từ hộp thoại, rồi dán ID và secret. Ứng dụng External ở trạng thái Testing phải đăng nhập lại sau mỗi 7 ngày.
• Service account (Google Workspace): tạo service account với khóa JSON, cấp cho client ID của nó quyền domain-wide delegation với cùng ba scope trong Admin console, rồi dán khóa JSON và người dùng mà nó thay mặt. Một kết nối đọc với tư cách một người dùng.

Google Drive

Chọn My Drive, Shared with me, các shared drive, hoặc một thư mục. Docs được đọc dưới dạng Markdown, Sheets dưới dạng CSV (trang tính đầu tiên), Slides dưới dạng văn bản. Google xuất tối đa 10 MB của một Doc, Sheet hoặc Slides; các tệp khác trên 100 MB bị bỏ qua.

Gmail

Chọn các nhãn (mặc định INBOX) và số ngày thư (365). Mỗi cuộc hội thoại là một tài liệu; tệp đính kèm được liệt kê theo tên. Thư nháp, thư rác và thùng rác không bao giờ được đọc.

Google Calendar

Chọn các lịch (mặc định primary), số ngày về trước (365) và về sau (180). Mỗi sự kiện, và mỗi lần lặp của sự kiện định kỳ, là một tài liệu.

IMAP, Dropbox và Box

Hộp thư IMAP

• Phần lớn dịch vụ thư cần mật khẩu ứng dụng: Gmail (imap.gmail.com), iCloud (imap.mail.me.com), Yahoo (imap.mail.yahoo.com), Zoho (imap.zoho.com). Hộp thư Outlook.com và Microsoft 365 không nhận mật khẩu qua IMAP.
• Kết nối: máy chủ thư, Bảo mật (TLS trên cổng 993, hoặc STARTTLS trên 143), tên người dùng và mật khẩu.
• Nguồn: các thư mục, mỗi dòng một thư mục; tùy chọn ngày Nhận từ ngày và Chỉ các tên miền này. Tệp đính kèm được lập chỉ mục thành tài liệu riêng trừ khi bạn tắt. Các thư mục được mở ở chế độ chỉ đọc.

Dropbox

• Tại dropbox.com/developers/apps, tạo một ứng dụng Scoped access, Full Dropbox với files.metadata.read và files.content.read, thêm địa chỉ chuyển hướng, rồi sao chép app key và secret. Access token dùng được để thử nhanh và hết hạn sau bốn giờ.
• Nguồn: đường dẫn hoặc liên kết thư mục; để trống sẽ đọc toàn bộ Dropbox. Tài liệu Paper được tính là Markdown trong phần chọn loại tệp. Tệp tối đa 100 MB.

Box

• Trong Box Developer Console, tạo một Platform App với User Authentication (OAuth 2.0), thêm địa chỉ chuyển hướng, chỉ giữ Read all files and folders stored in Box, rồi sao chép client ID và secret. Developer token dùng được trong 60 phút.
• Hoặc Thông tin xác thực ứng dụng (ứng dụng máy chủ): một Platform App dùng Server Authentication (Client Credentials Grant) đã được quản trị viên Box phê duyệt. Nó đọc với tư cách tài khoản dịch vụ của ứng dụng (enterprise ID của bạn) hoặc một người dùng (user ID của người đó).
• Phiên đăng nhập còn hiệu lực khi Proxyma đồng bộ ít nhất 60 ngày một lần.
• Nguồn: ID hoặc liên kết thư mục; để trống sẽ đọc All Files. Tệp tối đa 100 MB.

CRM và hỗ trợ khách hàng

HubSpot

• Tạo một Service Key (Settings → Integrations → Service Keys) với crm.objects.companies.read, crm.objects.contacts.read, crm.objects.deals.read, tickets và, để hiển thị tên người phụ trách, crm.objects.owners.read. Token của legacy private app cũng dùng được, hoặc đăng nhập bằng một ứng dụng HubSpot.
• Nguồn: các loại bản ghi cần lập chỉ mục; mặc định là công ty, giao dịch và ticket.
• Kết nối đọc toàn bộ tài khoản, bất kể một người dùng cụ thể được xem gì trong HubSpot.

Salesforce

• Tạo một External Client App với các OAuth scope api, id, profile, email, address, phone và refresh_token, offline_access.
• Đăng nhập bằng Salesforce (org production): đặt callback là địa chỉ trong hộp thoại và bật PKCE. Hoặc JWT bearer cho một người dùng tích hợp: tải chứng chỉ lên ứng dụng rồi dán consumer key, tên người dùng và khóa riêng.
• Đặt URL My Domain, ví dụ https://acme.my.salesforce.com.
• Nguồn: các đối tượng; mặc định là account, opportunity và case. Trường tùy chỉnh không được đọc.

Zendesk

• Trong Admin Center → Apps and integrations → APIs → Zendesk API, bật Token access và thêm một token. Kết nối nhận subdomain, email của một nhân viên hỗ trợ và token, và đọc những gì nhân viên đó xem được. Hoặc đăng nhập bằng một OAuth client.
• Nguồn: Phiếu hỗ trợ (bật), Ghi chú nội bộ (tắt), Bài viết Help Center (tắt), ngôn ngữ và mục của bài viết.

Freshdesk

• Sao chép API key trong Profile settings → View API key. Kết nối nhận domain và key, và đọc những gì nhân viên đó xem được.
• Nguồn: Phiếu hỗ trợ (bật), Ghi chú riêng tư (tắt), Bài viết cơ sở tri thức (tắt), danh mục bài viết.

Zoom

Zoom

• Ứng dụng Server-to-Server OAuth (quản trị viên tài khoản, tại marketplace.zoom.us): thêm các scope user:read:user:admin, user:read:list_users:admin, cloud_recording:read:list_user_recordings:admin, cloud_recording:read:list_recording_files:admin, meeting:read:list_summaries:admin, meeting:read:summary:admin và meeting:read:list_past_participants:admin, kích hoạt nó, rồi dán account ID, client ID và secret.
• Hoặc Đăng nhập bằng Zoom qua một General App với cùng các scope nhưng không có :admin.
• Nguồn: địa chỉ email của những người cần đọc (để trống: chính bạn; *: mọi người, với ứng dụng Server-to-Server) và số ngày cuộc họp (365).
• Bản ghi lời thoại cần bật ghi hình đám mây kèm bản ghi âm thanh; tóm tắt cần bật tóm tắt cuộc họp của AI Companion.
• Bản ghi lời thoại chứa những gì mọi người đã nói. Chỉ lập chỉ mục những cuộc họp mà người tham dự có thể chờ đợi điều đó.

Microsoft 365 Enterprise

OneDrive, SharePoint, Teams và Outlook, được đọc bằng chính tài khoản Microsoft của từng người. Nguồn Microsoft 365 không chia sẻ được.

1. Quản trị viên Microsoft 365 đăng ký một ứng dụng single-tenant trong Microsoft Entra ID, với redirect URI loại Web là https://<your server>/api/v1/microsoft/oauth/callback, một client secret, và các quyền Microsoft Graph dạng delegated sau:
   • Mọi nguồn: openid, profile, email, offline_access
   • OneDrive và SharePoint: Files.Read.All, Sites.Read.All
   • Outlook: Mail.Read, Mail.Read.Shared, Calendars.Read, Calendars.Read.Shared
   • Kênh Teams: Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All (cần admin consent)
   • Trò chuyện Teams: Chat.Read
2. Quản trị viên cấp cao nhập tenant ID, client ID và client secret trong Cài đặt → Mạng → Microsoft 365, và bật các nguồn mà tổ chức cho phép: kênh Teams, trò chuyện Teams, Outlook. OneDrive và SharePoint không cần công tắc.
3. Mỗi người thêm một kết nối Microsoft 365 trong Cài đặt → Kết nối và chọn Đăng nhập. Ai đã đăng nhập trước khi một công tắc được bật thì đăng nhập lại.

OneDrive

Toàn bộ OneDrive của bạn, hoặc một thư mục theo đường dẫn, ví dụ Documents/Reports, kèm mọi thứ bên trong. Sổ tay OneNote bị bỏ qua.

SharePoint

Dán địa chỉ của site và đặt tên. Các trang của site và tệp trong mọi thư viện tài liệu đều được lập chỉ mục.

Kênh Teams

Một kênh của một nhóm bạn đã tham gia, theo tên nhóm và tên kênh. Mỗi tin nhắn là một tài liệu, kèm các trả lời.

Trò chuyện Teams

Các cuộc trò chuyện riêng và nhóm của chính bạn, mỗi cuộc trò chuyện mỗi ngày (UTC) là một tài liệu. Chọn số ngày về trước; 0 là đọc tất cả.

Outlook

Một thư mục thư (kèm thư mục con nếu bạn chọn) hoặc một lịch, từ hộp thư của bạn hoặc một hộp thư dùng chung bạn mở được. Lịch bao gồm 365 ngày về trước và về sau; Quản trị viên cấp cao đặt khoảng này trong Cài đặt → Mạng.

Nguồn tùy chỉnh

• Nguồn tùy chỉnh chứa các tài liệu do script và công cụ của bạn (Zapier, Make, n8n, một tác vụ cron) đẩy vào. Proxyma không tự kéo dữ liệu về.
• Thêm nguồn trong Nguồn dữ liệu → Kết nối → Nguồn tùy chỉnh, mở nguồn và chọn API nạp dữ liệu để xem địa chỉ endpoint, rồi chọn Tạo token. Token chỉ hiển thị một lần.
• Token chỉ mở các endpoint nạp dữ liệu của đúng nguồn đó. Thu hồi token ngay trên bảng này.
• Trợ lý có thể lưu một ghi chú vào nguồn tùy chỉnh của bạn; như mọi thao tác ghi, ở chế độ Hỏi trước trợ lý sẽ hỏi bạn trước khi lưu.
• Các lệnh gọi, trường dữ liệu và giới hạn có trong tài liệu API.
• Enterprise Chỉ chủ sở hữu nguồn mới đẩy được tài liệu và tạo token. Chia sẻ nguồn cho phép người khác tìm kiếm trong đó.

Định dạng và OCR

• PDF; Word, Excel và PowerPoint (.docx, .xlsx, .xls, .pptx và các phiên bản có macro); Outlook .msg; EPUB; CSV, Markdown, văn bản thuần và HTML; mã nguồn C và C++; script shell, batch và PowerShell; tệp AUTOSAR và phần mềm nhúng (.arxml, .dbc, .a2l, linker script, hợp ngữ).
• Hãy lưu các tệp .doc và .ppt cũ thành .docx và .pptx trước.
• Bảng trong tệp PDF được giữ nguyên dạng bảng.
• Tệp PDF được quét cần OCR: chọn một mô hình OCR trong Cài đặt → Chuyển đổi, hoặc bộ máy Tesseract. Tesseract đi kèm Proxyma và đọc được tiếng Anh và tiếng Việt (đặt Ngôn ngữ Tesseract là eng+vie để dùng cả hai). Trên Linux, nếu hệ thống bỏ qua các gói được khuyến nghị: sudo apt install tesseract-ocr tesseract-ocr-eng tesseract-ocr-vie.

Đồng bộ và trạng thái

• Mỗi tài liệu đi qua các bước phát hiện, tải về, chuyển đổi và tạo vector nhúng. Một tài liệu lỗi hiển thị lý do và không làm dừng các tài liệu còn lại.
• Mỗi lần đồng bộ chỉ xử lý những gì đã thay đổi. Phần lớn dịch vụ đồng bộ mỗi giờ; Gmail và IMAP mỗi 30 phút, monday.com mỗi 2 giờ, thư mục chia sẻ mạng mỗi 6 giờ và trang web mỗi ngày một lần.
• Đồng bộ ngay chạy một lần đồng bộ đầy đủ, đồng thời gỡ những gì đã bị xóa ở nguồn.
• Sau khi đổi mô hình vector nhúng, mở từng nguồn và chọn Lập chỉ mục lại.
• Khi một dịch vụ giới hạn tần suất truy vấn, việc đồng bộ sẽ chờ, hoặc dừng lại và tiếp tục lần sau. Không mất gì.

Sử dụng Proxyma

• Hỏi bằng ngôn ngữ tự nhiên. Proxyma trả lời từ các đoạn văn nó tìm được và trích dẫn chúng. Khi không có nội dung liên quan, nó nói thẳng như vậy.
• Tìm kiếm đối chiếu từ khóa và ý nghĩa cùng lúc, nên cả một mã lỗi chính xác lẫn một mô tả mơ hồ đều dùng được.
• Nhắc tới một nguồn để tìm trong nó trước, hoặc một kỹ năng để nạp nó cho một tin nhắn.
• Đính kèm một tệp vào tin nhắn để tác nhân đọc.

Các cuộc trò chuyện

• Các cuộc trò chuyện được lưu ở nơi Proxyma chạy. Nhà cung cấp AI trực tuyến nhận cuộc trò chuyện để trả lời.
• Cuộc trò chuyện không hoạt động bị xóa sau 7 ngày trừ khi bạn ghim nó. Thay đổi trong Cài đặt → Lưu giữ dữ liệu → Cuộc trò chuyện (ngày); 0 là giữ lại.
• Enterprise Cuộc trò chuyện của mỗi người là của riêng họ. Quản lý tài khoản của ai đó không mở được các cuộc trò chuyện của họ.

Đồ thị tri thức

Proxyma có thể trích xuất những thứ tài liệu nhắc tới - thành phần, dịch vụ, con người - và mối quan hệ giữa chúng thành một đồ thị. Tác nhân dùng nó để trả lời các thứ liên quan với nhau thế nào, ai làm gì, và điều gì đã xảy ra khi nào, kèm trích dẫn đoạn văn làm căn cứ cho từng mối quan hệ.

1. Trong Cài đặt → Tìm kiếm, bật Đồ thị tri thức và chọn mô hình trích xuất. Nếu việc trích xuất hết thời gian chờ, hãy tăng Thời gian chờ trích xuất.
2. Trong phần cài đặt của một nguồn, bật Xây dựng đồ thị tri thức. Những gì đã lập chỉ mục được trích xuất ở chế độ nền; không có gì bị lập chỉ mục lại.

• Việc trích xuất tốn một lần gọi mô hình cho mỗi đoạn văn. Hãy bắt đầu với một nguồn.
• Jira, Confluence, Bitbucket và SVN còn cho các mối quan hệ mà chính trường dữ liệu của chúng ghi lại (người được giao, issue liên kết, cây trang, tác giả, người duyệt), kèm ngày tháng. Những mối quan hệ này không cần mô hình.
• Đồ thị tri thức trong tìm kiếm (Cài đặt → Tìm kiếm, tắt mặc định) xếp hạng kết quả tìm kiếm theo cả đồ thị.
• Để xem đồ thị, mở một nguồn và chọn biểu tượng đồ thị. Kéo để xoay, cuộn để phóng to, giữ Shift và kéo để di chuyển, bấm một điểm để xem các liên kết của nó. Số sao đặt số điểm được vẽ.
• Tắt đồ thị cho một nguồn sẽ xóa những gì nguồn đó đã đưa vào đồ thị. Chỉ mục của nó vẫn giữ nguyên.
• Enterprise Mỗi người chỉ thấy các mối quan hệ được nêu trong những nguồn họ đọc được.

Bộ nhớ

• Tác nhân lưu các dữ kiện và sở thích của bạn, và xem lại chúng trước khi tìm kiếm.
• Cài đặt → Bộ nhớ liệt kê chúng trong Về bạn và Kiến thức: sửa, chuyển hoặc xóa bất kỳ mục nào.
• Enterprise Mỗi người chỉ thấy mục của riêng mình.

Tác nhân

Tác nhân tìm kiếm trong các nguồn của bạn và có thể đọc trực tiếp các hệ thống của bạn. Ở nơi bạn cho phép, nó thay đổi chúng: bình luận vào một ticket, chuyển trạng thái, mở một pull request.

Ba lớp kiểm soát

Mọi thay đổi đều phải qua cả ba.

1. Quyền, theo từng kết nối. Kết nối Jira, Confluence và Bitbucket (Data Center hoặc Server) có công tắc Đọc (bật) và Ghi (tắt) trong Cài đặt → Kết nối. Tắt Ghi sẽ từ chối mọi thay đổi ngay lập tức; nó không hoàn tác những thay đổi trước đó.
2. Chế độ, bên cạnh mô hình dưới ô nhập tin nhắn. Nó bắt đầu ở Hỏi trước mỗi lần bạn mở Proxyma.
   • Hỏi trước: mỗi thay đổi chờ Cho phép một lần, Cho phép trong cuộc trò chuyện này hoặc Từ chối. Không trả lời thì bị từ chối sau 5 phút khi trang đang mở, hoặc 30 phút khi trang đã đóng.
   • Tự động: thay đổi được thực hiện mà không hỏi. Quyền Ghi vẫn phải bật.
   • Chỉ đọc: mọi thay đổi đều bị từ chối.
3. Thông tin đăng nhập của chính bạn. Mọi hành động dùng kết nối của bạn, nên tác nhân không làm được gì mà bạn không làm được, và thay đổi xuất hiện dưới tên bạn.

Tác nhân truy cập được gì

• Tác nhân cũng có thể gọi trực tiếp bất kỳ điểm cuối API nào của Jira, Confluence hoặc Bitbucket. Lệnh đọc cần bật Đọc; lệnh khác cần bật Ghi và, ở chế độ Hỏi trước, sự chấp thuận của bạn.
• Duyệt hoặc merge một pull request không thể hoàn tác từ Proxyma, và lượt duyệt được tính vào điều kiện merge dưới tên bạn.
• Tệp Office: tác nhân tạo và sửa tệp Word, Excel và PowerPoint. Trên Desktop nó có thể lưu vào máy tính của bạn, có hỏi trước; trên máy chủ nó làm việc với tệp đính kèm trong một container cô lập.
• Tìm kiếm web dùng DuckDuckGo khi chưa thiết lập gì, hoặc Google khi có khóa Custom Search và ID công cụ tìm kiếm trong Cài đặt → Tìm kiếm → Tìm kiếm web. Nó vẫn được dùng ngay cả với mô hình cục bộ.

Tác nhân phụ

• Tác nhân giao từng phần việc cho các tác nhân phụ, mỗi tác nhân có ngữ cảnh riêng. Chúng chạy nền trong khi bạn tiếp tục trò chuyện, và đi qua cùng ba lớp kiểm soát; ở chế độ Hỏi trước, lời nhắc nêu tên tác nhân phụ.
• Mỗi tác nhân phụ có một khung trong cuộc trò chuyện với nút Dừng riêng. Nút bên cạnh mô hình mở cửa sổ các tác nhân: mọi tác nhân, các bước của nó, và những gì nó đã dùng và chi phí.
• Chúng dùng mô hình của tác nhân trừ khi bạn chọn mô hình khác trong Cài đặt → Tác nhân → Tác nhân phụ. Một mô hình rẻ hơn ở đó giúp việc đọc dài bớt tốn kém.
• Khi chạm giới hạn tốc độ của nhà cung cấp, các tác nhân chờ và thử lại tới 10 phút.

Tác nhân làm việc trong bao lâu

• Một vòng lặp là một lần gọi mô hình cùng các lần gọi công cụ của nó. Khi chạm giới hạn, tác nhân hỏi: Tiếp tục cho nó thêm chừng ấy vòng; Dừng ở đây để nó trả lời với những gì đã có.
• Các công cụ khác dừng sau một phút. Thời gian chờ bạn chấp thuận không được tính.
• Dừng kết thúc một lượt chạy bất cứ lúc nào.
• Bộ nhớ đệm prompt (Anthropic, OpenRouter, và LiteLLM trên Anthropic Messages): Tự động giữ cuộc trò chuyện trong bộ nhớ đệm 5 phút, hoặc 1 giờ khi tác nhân phụ đang làm việc hay sau một khoảng nghỉ dài hơn.

Máy chủ MCP

Tác nhân có thể dùng công cụ của các máy chủ MCP khác.

1. Trong Cài đặt → Kết nối → Thêm kết nối, chọn Máy chủ MCP.
2. Chọn cách truyền tải: Streamable HTTP hoặc SSE cho máy chủ ở một địa chỉ, hoặc Lệnh cục bộ cho một chương trình Proxyma khởi chạy, như npx hoặc uvx, mỗi dòng một tham số.
3. Với một địa chỉ, chọn cách đăng nhập: không xác thực, bearer token, header tùy chỉnh, hoặc OAuth (lưu lại, rồi Đăng nhập).
4. Chọn Kiểm tra; nó cho biết máy chủ cung cấp bao nhiêu công cụ.

• Tác nhân thấy mỗi máy chủ như một kỹ năng tên MCP: kèm tên kết nối.
• Mọi lần gọi công cụ của nó đều chờ bạn chấp thuận, trừ ở chế độ Tự động; chế độ Chỉ đọc từ chối chúng.
• Enterprise Chỉ Quản trị viên cấp cao mới thêm được lệnh cục bộ, hoặc chia sẻ một máy chủ với mọi người.

Kiểm tra mọi thứ hoạt động

1. Trong khung trò chuyện, hỏi: Chạy tự kiểm tra.
2. Chọn chỉ kiểm tra việc đọc, hoặc cả đọc và ghi với một dự án Jira, không gian Confluence hoặc kho Bitbucket dùng để thử; những gì nó tạo ra sẽ bị xóa khi kết thúc.
3. Đính kèm một tệp PDF hoặc Word khi được hỏi.
4. Mỗi mục kiểm tra báo PASS, FAIL, SKIPPED hoặc NEEDS YOU, kèm cách khắc phục cho từng lỗi.

Rào chắn

Rào chắn kiểm tra những gì mọi người gửi, những gì tác nhân đọc và những gì nó trả lời. Chúng bật ngay từ đầu, không cần mô hình AI và không gửi gì đi đâu. Thiết lập nằm trong Cài đặt → Rào chắn và áp dụng cho toàn bộ bản cài đặt.

• Tin nhắn bị chặn sẽ bị từ chối và không được lưu. Nguồn bị giữ lại sẽ bị bỏ ra và tác nhân tiếp tục. Câu trả lời được lưu với phần khớp đã bị lược bỏ, ví dụ [redacted: secret].
• Thông báo và nhật ký nêu tên quy tắc và nhóm đã kích hoạt, không bao giờ nêu phần văn bản đã khớp.
• Văn bản được chuẩn hóa trước, nên ký tự vô hình và chữ cái trông giống nhau không che giấu được phần khớp.
• Vài trăm ký tự cuối của câu trả lời hiện ra khi nó hoàn tất, không hiện từng chữ.

Theo dõi trước khi áp dụng

1. Đặt Chế độ là Chỉ theo dõi: mọi kiểm tra vẫn chạy và không có gì bị chặn.
2. Đọc Nhật ký → Rào chắn: bao nhiêu lượt kiểm tra đã chạy, những gì lẽ ra đã bị giữ lại, và quy tắc nào đã kích hoạt.
3. Khi kết quả hợp lý, đặt Chế độ là Áp dụng.

Quy tắc của riêng bạn

• Đánh giá ý nghĩa bằng mô hình (tắt) gửi mỗi tin nhắn, và với Kiểm tra cả câu trả lời là cả mỗi câu trả lời, tới Mô hình cho rào chắn mà bạn chọn. Nó đánh giá theo một danh sách có sẵn (bạo lực, tự gây hại, nội dung tình dục liên quan trẻ vị thành niên, vũ khí, quấy rối và thù ghét) và các quy tắc của riêng bạn.
• Quy tắc từ tài liệu của bạn: tải lên các chính sách (Markdown, PDF, Word, Excel hoặc PowerPoint, tối đa 20 MB mỗi tệp). Chỉ những điều khoản liên quan tới một tin nhắn mới được gửi đi. Tài liệu chính sách không bao giờ xuất hiện trong kết quả tìm kiếm.
• Khi bật những tính năng này, văn bản được đánh giá sẽ tới nhà cung cấp của mô hình rào chắn và mô hình vector nhúng. Dùng mô hình cục bộ để giữ nó trên máy.
• Nếu không kết nối được tới mô hình, tin nhắn vẫn được cho qua, trừ khi bật Từ chối khi không kết nối được tới mô hình.
• Phát hiện câu lệnh hệ thống bị lộ (tắt) từ chối câu trả lời trích dẫn chỉ dẫn của tác nhân; nó không bắt được việc diễn đạt lại.
• Làm chậm các lần thử lặp lại (tắt) tạm dừng người bị từ chối nhiều lần liên tiếp, cho tới khi khởi động lại. Dán nhật ký có chứa token có thể kích hoạt nó.
• Lưu lại phần nội dung khớp quy tắc (tắt) giữ những gì mỗi quy tắc đã khớp, chỉ trong bộ nhớ (200 quyết định, mỗi quyết định 120 ký tự), để quản trị viên đọc trong Nhật ký.

Rào chắn là bộ lọc văn bản, không phải cơ chế kiểm soát truy cập. Mẫu nhận diện chèn chỉ dẫn bắt được các nỗ lực sao chép nguyên văn, không bắt được cách diễn đạt khéo léo. Nếu chính bước kiểm tra truy xuất bị lỗi, nguồn đó vẫn được cho qua.

MCP và HTTP API

Claude Code, Claude Desktop, ChatGPT, Gemini CLI, GitHub Copilot, Cursor và các tập lệnh của riêng bạn có thể tìm kiếm những gì Proxyma đã lập chỉ mục, qua MCP tại /mcp và HTTP API. Chúng thấy những gì chủ của token thấy. Cài đặt → Trợ lý AI hiển thị cấu hình cho từng máy khách, sẵn sàng để sao chép. Xem tài liệu tham chiếu HTTP API và MCP.

Duy trì hoạt động

Cập nhật

• Community Desktop tự cập nhật: Cài đặt → Cập nhật kiểm tra mỗi ngày một lần theo mặc định (hoặc 6 giờ một lần, mỗi tuần một lần, hoặc không bao giờ), chỉ tải những phần đã thay đổi, đối chiếu chúng với mã kiểm tra đã ký của bản phát hành, và chờ bạn chọn khởi động lại và cài đặt. Phiên bản không khởi động được sẽ tự quay về bản trước. Dữ liệu của bạn không bị động tới. Bản dựng phát triển (tắt) cung cấp thêm các bản dựng thử nghiệm.
• Community Home Server: docker compose pull proxyma, rồi ./install.sh. Nếu đã cố định PROXYMA_IMAGE, hãy đổi nó trước.
• Enterprise Sao lưu cơ sở dữ liệu, thay thư mục gói cài đặt nhưng giữ .env, keys/, data/ và docker-compose.override.yml nếu có, rồi docker compose pull proxyma-server (hoặc đổi PROXYMA_IMAGE đã cố định) và ./install.sh. Hãy nêu tên dịch vụ: docker compose pull không kèm tên sẽ lỗi ở image cơ sở dữ liệu được dựng tại chỗ. Lược đồ cơ sở dữ liệu được cập nhật khi khởi động.
• Kiểm tra image là của chúng tôi: cosign verify --key https://proxyma.ai/keys/cosign-release.pub ghcr.io/proxyma-ai/proxyma-enterprise-server:<version> (hoặc proxyma-homeserver).

Nhật ký

Community Cài đặt → Nhật ký. Enterprise Quản trị → Nhật ký, cho mọi người, có bộ lọc Người dùng.

• Chọn khoảng thời gian (7, 30 hoặc 90 ngày, hoặc 12 tháng), rồi tìm kiếm, lọc và sắp xếp. Mở một dòng để xem mọi thứ được ghi lại cùng nó.
• Tải xuống dạng CSV hoặc JSON: các mục theo bộ lọc hiện tại, tối đa 10.000.
• Community Xóa nhật ký xóa các mục của một thẻ, và chính lần xóa được ghi lại. Xóa Lần gọi LLM thì giới hạn chi tiêu đếm lại tháng này từ đầu.
• Enterprise Không ai xóa được lần gọi công cụ, lượt kiểm tra rào chắn hay hoạt động. Quản trị viên cấp cao có thể xóa Lần gọi LLM; khi đó giới hạn hằng tháng của bản triển khai đếm lại từ 0. Đầu vào và kết quả của lần gọi công cụ chỉ hiển thị cho Quản trị viên cấp cao.

Lưu giữ dữ liệu

Cài đặt → Lưu giữ dữ liệu. Dọn dẹp mỗi ngày; 0 là giữ mãi mãi.

Nhập và xuất thiết lập

Cài đặt → Nhập & Xuất dữ liệu sao chép cấu hình sang một bản cài đặt khác dưới dạng một tệp JSON. Đây không phải bản sao lưu: tệp không chứa cuộc trò chuyện, tài liệu hay chỉ mục.

• Xuất: đánh dấu các nhóm (mang tên các thẻ trong Cài đặt). Để kèm thông tin đăng nhập, giữ Kèm theo thông tin đăng nhập, được mã hóa bằng một cụm mật khẩu và nhập cụm mật khẩu dài ít nhất 12 ký tự; cụm mật khẩu này không thể khôi phục.
• Nhập: nhập cụm mật khẩu nếu có, Chọn tệp tin (rồi Đọc tệp này), bỏ đánh dấu những gì không muốn, xem các thay đổi, rồi Nhập tệp này.
• Việc nhập chỉ thêm mới và cập nhật. Tên đã tồn tại được giữ nguyên.
• Không bao giờ được xuất: giấy phép, giao diện, phiên đăng nhập Microsoft 365, token API và tài khoản, cùng công tắc Đọc và Ghi của từng kết nối (kết nối được nhập bắt đầu với Đọc bật và Ghi tắt).
• Enterprise Chỉ Quản trị viên cấp cao; tệp chỉ mang theo kết nối của chính họ.

Dữ liệu nằm ở đâu, và sao lưu

• Tài liệu của bạn vẫn ở nguyên chỗ; Desktop không bao giờ sao chép chúng.
• Thông tin đăng nhập được mã hóa bằng một khóa lưu trong thư mục dữ liệu (trên Windows, được DPAPI bảo vệ cho tài khoản của bạn). Mất thư mục dữ liệu nghĩa là phải lập chỉ mục lại và nhập lại thông tin đăng nhập.
• Enterprise Mất cơ sở dữ liệu là không thể khôi phục. Hãy khôi phục data/ và cơ sở dữ liệu cùng nhau, nếu không Proxyma sẽ liệt kê những tài liệu mà nó không đọc được.
• Enterprise Cơ sở dữ liệu đi kèm được sao lưu liên tục bằng pgBackRest vào data/pgbackrest-repo; với cơ sở dữ liệu của riêng bạn, Proxyma tạo bản chụp pg_dump, nên hãy giữ cả bản sao lưu của riêng bạn. Khôi phục trong Quản trị → Vận hành → Sao lưu: Khôi phục, rồi gõ tên tệp của bản sao lưu. Việc khôi phục thay thế toàn bộ dữ liệu, và Proxyma không dùng được cho tới khi hoàn tất.

Quản trị Enterprise Enterprise

Người dùng và vai trò

• Thêm người dùng trong Quản trị → Người dùng, để họ đăng nhập một lần, hoặc đặt PROXYMA_SELF_REGISTRATION=true.
• Quên mật khẩu: Proxyma không gửi email. Quản trị viên cấp cao mở người đó và chọn Tạo liên kết đặt lại mật khẩu; liên kết dùng được một lần, trong vòng một giờ.
• Xóa tài khoản chờ 7 ngày, trong thời gian đó có thể khôi phục. Tài khoản đăng nhập một lần sẽ bị xóa dữ liệu ngay và tài khoản được giữ lại.

Đăng nhập một lần

Email và mật khẩu vẫn dùng được bên cạnh các cách này. Đặt các biến trong .env rồi chạy ./install.sh. Đăng ký mỗi địa chỉ chuyển hướng chính xác: https, tên máy mọi người gõ, không có dấu gạch chéo ở cuối.

Đăng nhập một lần dựa vào header X-Forwarded-Proto từ reverse proxy của bạn; thiếu nó, địa chỉ chuyển hướng dùng http:// và thất bại.

Giới hạn chi tiêu

• Cài đặt → Mức sử dụng & Chi phí: giới hạn hằng tháng của bản triển khai, và hạn mức mặc định của từng người (hằng tháng, 5 giờ và hằng tuần). Mỗi người thấy một dấu hiệu khi vượt 80% hạn mức 5 giờ của mình.
• Quản trị → Người dùng, mở một người: hạn mức và hạn mức lưu trữ của riêng họ.
• Mỗi người xem mức sử dụng của mình trong Cài đặt → Tài khoản.

Chia sẻ nguồn dữ liệu

• Chủ nguồn chia sẻ nó từ trang Nguồn dữ liệu; sau đó mọi người đều tìm kiếm được trong nó. Chia sẻ là tất cả hoặc không có gì.
• Các hành động trực tiếp của họ trên hệ thống đó vẫn cần kết nối của riêng họ.

Quản trị

Quản trị viên mở được thiết lập hệ thống; chỉ Quản trị viên cấp cao mới thay đổi được.

Khách hàng trọng điểm

Một bản đánh giá chung về một khách hàng quan trọng: tình trạng của khách hàng đó, và nên làm gì tiếp theo. Tác nhân đọc các nguồn bạn liên kết và đề xuất dữ kiện, điểm đánh giá và bước đi tiếp theo kèm bằng chứng; không đề xuất nào có hiệu lực cho tới khi một người xác nhận.

1. Khách hàng trọng điểm → Khách hàng mới: tên, hạng, mục tiêu, ngày gia hạn và ARR. Bạn là Chủ sở hữu, và kỳ đánh giá đầu tiên được mở.
2. Trong Nguồn cho trợ lý, liên kết các nguồn chứa hợp đồng, ticket, biên bản và doanh thu của khách hàng. Liên kết không cấp cho ai quyền truy cập nguồn.
3. Chia sẻ nó, và cấp vai trò cho từng người.
4. Mở khung trợ lý và chọn Chạy đánh giá sức khỏe. Đề xuất xuất hiện ở Hồ sơ, Sức khỏe, Con người và Cơ hội.
5. Ở Sức khỏe, chấm điểm từng câu hỏi từ 1 tới 5 rồi chọn Xác nhận và tiếp tục. Ở Hồ sơ, xác minh từng dữ kiện.
6. Đề nghị trợ lý Soạn các bước đi tiếp theo, rồi Chấp nhận (kèm người phụ trách và hạn chót), Từ chối hoặc Hoãn từng bước. Bước được chấp nhận trở thành hành động trong Kế hoạch.
7. Ở Báo cáo, soạn thảo, Lưu bản nháp, và Chủ sở hữu chọn Ký duyệt. Báo cáo đã ký không sửa được.

• Trợ lý không thể xác nhận điểm, quyết định bước đi, ký duyệt, thay đổi thành viên, xóa, hay ghi lại cảm nhận của một bên liên quan. Các thay đổi khác của nó tuân theo chế độ của khung trợ lý.
• Tổng quan cho thấy điểm sức khỏe (0-100, từ các điểm đã xác nhận), ARR, số ngày tới gia hạn, khoảng trống, độ phủ người bảo trợ và tiến độ kế hoạch. Nhập doanh thu nhận một tệp CSV có cột tháng, cột thực tế và cột kế hoạch tùy chọn.
• Hoạt động liệt kê mọi thay đổi kèm giá trị trước và sau. Kỳ đánh giá mới mang theo các điểm đã xác nhận và các hành động còn mở.
• Quản trị viên cấp cao đọc được mọi khách hàng trọng điểm, và chỉ thay đổi được những khách hàng mà họ là thành viên.

Dữ liệu và quyền riêng tư

• Tài liệu của bạn được lập chỉ mục và lưu ở nơi Proxyma chạy.
• Những gì rời đi: văn bản gửi tới các nhà cung cấp AI bạn chọn (để lập chỉ mục, trả lời, trích xuất đồ thị, đánh giá rào chắn); các lượt tìm kiếm web của tác nhân và các trang nó mở; những gì nó hỏi các hệ thống bạn kết nối; và góp ý bạn gửi.
• Community Cài đặt → Giới thiệu → Quyền riêng tư → Gửi dữ liệu chẩn đoán tới Proxyma (tắt) gửi một báo cáo hằng ngày về loại lỗi, thời gian xử lý và các tính năng đang dùng, không bao giờ có nội dung. Khi bật, việc đánh giá một câu trả lời sẽ gửi câu trả lời đó và câu hỏi của nó, ở dạng ẩn danh. Nhật ký → Dữ liệu chẩn đoán → Xem những gì sẽ được gửi cho thấy chính xác bản báo cáo. Community không bao giờ liên lạc với máy chủ giấy phép.
• Enterprise Enterprise Server không bao giờ gửi dữ liệu chẩn đoán hay câu trả lời được đánh giá. Nó liên lạc với máy chủ giấy phép để dùng thử và để xác nhận giấy phép.
• Đường dẫn tuyệt đối trên máy chủ được loại bỏ khỏi những gì tác nhân hiển thị cho bạn.
• Enterprise Tìm kiếm, trò chuyện, API và MCP chỉ truy cập các nguồn của chính người gọi và các nguồn được chia sẻ. Quản trị viên đọc được lần gọi công cụ của mọi người trong nhật ký.
• Xóa một nguồn sẽ gỡ chỉ mục của nó. Trên Desktop, thư mục của bạn không bị động tới; tệp đã tải lên bị xóa cùng nguồn của chúng.
• Enterprise Xóa một tài khoản sẽ gỡ kết nối, cuộc trò chuyện, thiết lập và tệp tải lên của nó sau 7 ngày chờ; tệp trên đĩa được xóa ở chế độ nền.

Chính sách bảo mật nêu những gì Proxyma, với tư cách công ty, xử lý.

Xử lý sự cố

Không khởi động được

• Community Desktop: kiểm tra phần mềm diệt virus không chặn các tệp của Proxyma, kể cả %LOCALAPPDATA%\proxyma\parts\. Nếu lần khởi động đầu tiên dừng khi đang tải về, kiểm tra máy kết nối được tới GitHub rồi khởi động lại.
• Community Linux: chạy proxyma trong cửa sổ dòng lệnh để xem lỗi. Nếu nhật ký nhắc tới cơ sở dữ liệu vector, đọc ~/.local/share/proxyma/logs/chromadb.log; nguyên nhân thường là một tiến trình còn sót lại từ phiên bị buộc dừng. Nếu việc thiết lập Python thất bại, xóa runtime/ ở đó rồi khởi động lại.
• Enterprise Chạy docker compose logs proxyma-server. Gần như luôn là do cơ sở dữ liệu: sai máy chủ, sai mật khẩu, hoặc thiếu pgvector.
• Container khởi động lại hoặc hết bộ nhớ: cấp cho nó 4 GB; với cơ sở dữ liệu đi kèm, giảm PG_SHARED_BUFFERS hoặc chuyển cơ sở dữ liệu sang máy khác.

Ứng dụng hỏi mã truy cập, hoặc trả về 403 Community

• Home Server in mã truy cập ở mỗi lần khởi động, trừ khi bạn đặt PROXYMA_ACCESS_CODE. Desktop và Home Server lưu mã trong tệp access-code của thư mục dữ liệu.
• 403 cho mọi yêu cầu: tên máy bạn gõ không có trong PROXYMA_ALLOWED_HOSTS. homeserver, homeserver.lan và địa chỉ IP là những tên khác nhau.
• Dùng được trên máy đó nhưng không dùng được từ nơi khác: BIND_ADDR là 127.0.0.1, hoặc tường lửa chặn cổng.

Không có nhà cung cấp AI nào phản hồi, hoặc lỗi chứng chỉ

• Mở Cài đặt → Nhà cung cấp AI. Với Ollama, kiểm tra http://127.0.0.1:11434 có phản hồi trong trình duyệt.
• PKIX path building failed: dịch vụ dùng tổ chức cấp chứng chỉ của công ty. Desktop tin cậy những gì hệ điều hành của bạn tin cậy, nên hãy nhờ bộ phận IT cài chứng chỉ gốc. Enterprise Quản trị viên cấp cao dán chứng chỉ dạng PEM vào Cài đặt → Mạng → Chứng chỉ CA tùy chỉnh.

Tìm kiếm không ra gì, hoặc ra sai

• Kiểm tra trong Nguồn dữ liệu rằng việc lập chỉ mục đã xong, và xem các tài liệu bị lỗi.
• Sau khi đổi mô hình vector nhúng, hãy lập chỉ mục lại.
• Tài liệu quét phụ thuộc vào chất lượng OCR.
• Community Home Server: nếu nhật ký nhắc tới ChromaDB, đọc ./data/.local/share/proxyma/logs/chromadb.log. Việc lập chỉ mục có vẻ thành công trong khi kho vector đang hỏng.
• Câu trả lời chỉ tốt bằng những gì đã lập chỉ mục và mô hình trò chuyện.

Lập chỉ mục chậm

Bước tạo vector nhúng là nút thắt, nhất là với mô hình cục bộ trên máy tính xách tay. Hãy dùng nhà cung cấp vector nhúng trực tuyến, lập chỉ mục ít hơn, hoặc cứ để nó chạy; nó tiếp tục từ chỗ đã dừng.

Câu trả lời hiện ra một lúc, đăng nhập một lần thất bại, hoặc tải lên thất bại Enterprise

• Hiện ra một lúc, hoặc treo: reverse proxy đang đệm phản hồi. Trong nginx, đặt proxy_buffering off.
• Đăng nhập một lần chuyển hướng tới http://: proxy không gửi X-Forwarded-Proto.
• Tải tệp lớn thất bại: tăng giới hạn kích thước body của proxy; Proxyma nhận tới 200 MB.
• Let's Encrypt thất bại (profile tls): tên máy phải trỏ về máy chủ này với cổng 80 và 443 mở. Sau Cloudflare, dùng Full (strict), hoặc chỉ DNS cho tới khi có chứng chỉ.

Bản dùng thử không bắt đầu, hoặc có biểu ngữ giấy phép Enterprise

• Không liên lạc được máy chủ giấy phép: Proxyma tiếp tục thử, 15 phút một lần trong ngày đầu tiên rồi 6 giờ một lần; chọn Thử lại trong Cài đặt → Giấy phép, hoặc dùng khóa dùng thử.
• Đã dùng hết lượt thử: bản triển khai này đã dùng thử. Hãy liên hệ chúng tôi để mua giấy phép.
• Bản dùng thử hoặc giấy phép đã hết hạn: xem Khi bản dùng thử hoặc giấy phép hết hạn.

Nhận trợ giúp

Gửi góp ý từ menu ở góc trên bên phải (Gửi góp ý), hoặc gửi thư tới contact@proxyma.ai kèm phiên bản sản phẩm và số phiên bản (Cài đặt → Giới thiệu), điều bạn mong đợi, và điều đã xảy ra. Với máy chủ, hãy kèm docker compose logs --tail 200 proxyma-server (hoặc proxyma). Chúng tôi cố gắng trả lời trong vòng ba ngày làm việc.

Gỡ cài đặt

Tài liệu của chính bạn không bao giờ bị động tới.

• Windows: gỡ trong Add or remove programs. Chọn Yes để xóa cả dữ liệu của bạn. Sau đó xóa %USERPROFILE%\.proxyma\.
• Linux: sudo apt remove proxyma, rồi xóa ~/.local/share/proxyma/ và ~/.proxyma/.
• Home Server và Enterprise Server: docker compose down, rồi xóa thư mục. data/ và keys/ không bị xóa cho tới khi bạn tự xóa.
• Kubernetes: helm uninstall. Volume dữ liệu và Secret chứa mật khẩu cơ sở dữ liệu được giữ lại cho tới khi bạn xóa chúng.