Knowledge

Alibaba Cloud OSS

View as Markdown

Use the Alibaba Cloud OSS connector to index approved files from Object Storage Service. Create one connector per business knowledge directory, and restrict the RAM policy to the exact bucket and prefix that AIvis should read.

What You Need

ItemRequirement
BucketA private OSS bucket in the region that AIvis can reach.
PrefixA non-empty object prefix, such as knowledge/ or projects/legal/. AIvis trims leading /; do not use the whole bucket unless it is already curated.
RegionThe OSS region ID, such as cn-hangzhou or cn-shanghai.
CredentialA RAM user AccessKey ID and AccessKey Secret with read-only access to the target prefix.
EndpointUsually leave empty. AIvis derives https://oss-{region}.aliyuncs.com; use a custom endpoint only when required by your network path or CNAME policy.

OSS stores objects in a flat key space. Console folders are simulated by object-key prefixes and / delimiters. Granting access to a “folder” means granting access to every object whose key starts with that prefix.

Prepare Alibaba Cloud

  1. Sign in to Alibaba Cloud and open RAM.
  2. Create a RAM user dedicated to AIvis, such as aivis-oss-reader.
  3. Enable programmatic access and create an AccessKey pair for that RAM user.
  4. Save the AccessKey ID and AccessKey Secret immediately. Alibaba Cloud shows the AccessKey Secret only when the pair is created.
  5. Open the target OSS bucket and confirm its region, for example cn-hangzhou.
  6. Upload approved files under a dedicated prefix, for example knowledge/.

Minimum RAM Policy

Grant only list and read access. The list permission is scoped by oss:Prefix; object reads are scoped by the object resource path.

1{
2  "Version": "1",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": "oss:ListObjects",
7      "Resource": "acs:oss:*:*:aivis-docs",
8      "Condition": {
9        "StringLike": {
10          "oss:Prefix": [
11            "knowledge/",
12            "knowledge/*"
13          ]
14        }
15      }
16    },
17    {
18      "Effect": "Allow",
19      "Action": [
20        "oss:GetObject"
21      ],
22      "Resource": "acs:oss:*:*:aivis-docs/knowledge/*"
23    }
24  ]
25}

Do not grant oss:PutObject, oss:DeleteObject, bucket administration, or broad oss:* permissions. If objects use server-side encryption with KMS, confirm whether the RAM identity also needs kms:Decrypt for reads.

Credential Fields

Create an Alibaba Cloud OSS credential in AIvis:

AIvis FieldValue
Key ID / Access Key IDRAM user AccessKey ID.
Secret key / Secret Access KeyAccessKey Secret paired with the AccessKey ID.
Session TokenLeave empty for a permanent AccessKey. Fill it only when using temporary STS credentials.

Rotate the key through RAM if it was shared, lost, or created with excessive permissions.

Connector Fields

AIvis FieldExampleNotes
Connector nameAlibaba Cloud OSS knowledgeUse a name that identifies the bucket and business scope.
Bucket Nameaivis-docsBucket name only, not an oss:// URL.
Prefixknowledge/Must be non-empty. Use a trailing / for folder-like scopes.
Regioncn-hangzhouLowercase region ID.
Custom Endpoint URLLeave empty or https://oss-cn-hangzhou.aliyuncs.comOptional. Must include https:// and no credentials, query, or fragment.
ACL limitation confirmationCheckedObject ACLs are not synchronized into AIvis search permissions.
Document accessPrefer Private and assign users or groups.Split prefixes/connectors by audience.

The connector uses S3-compatible signed requests with virtual-hosted addressing. If your bucket is in a Chinese mainland region affected by Alibaba Cloud endpoint or CNAME policy changes, configure a valid custom endpoint and confirm it works from the AIvis worker network.

Verify

  1. Confirm the credential validates.
  2. Create the connector with a small prefix such as knowledge/test/.
  3. Run one index attempt and confirm only objects under that prefix appear.
  4. Search for a known title or sentence from an uploaded file.
  5. Confirm unselected prefixes and sensitive files are absent.
  6. Test as an unauthorized AIvis user and confirm private connector content is not searchable.

Troubleshooting

SymptomLikely cause and action
Credential is invalidAccessKey ID and Secret do not belong to the same RAM user, the Secret was copied incorrectly, or the key is disabled. Create or rotate the RAM AccessKey.
Bucket cannot be foundBucket name, region, or endpoint does not match the bucket. Check the OSS bucket region and endpoint.
Objects cannot be listedThe RAM policy is missing oss:ListObjects on the bucket or the oss:Prefix condition excludes the configured prefix.
Objects are listed but cannot be readThe RAM policy is missing oss:GetObject for bucket/prefix/*, or encrypted objects require additional decrypt permission.
Too many files are indexedPrefix is too broad. Use a business directory such as knowledge/ and mirror that prefix in RAM policy.
Users can search files they should not accessOSS object ACLs are not synchronized to AIvis. Use private document access or split connectors by audience.